Server Deployment

For quick setup, use the production compose file from the Portr repository:

https://github.com/amalshaji/portr/blob/main/docker-compose.prod.yaml

Services Overview

The production compose file includes 3 services:

• caddy: The reverse proxy for routing and SSL termination
• server: The combined admin and tunnel server
• postgres: The PostgreSQL database

Deployment Steps

Download the compose file

Download docker-compose.prod.yaml from the repository and place it in your server directory.

Set up environment variables

Create a .env file in the same directory with the following values:

PORTR_ADMIN_GITHUB_CLIENT_ID= #optional
PORTR_ADMIN_GITHUB_CLIENT_SECRET= #optional

PORTR_DOMAIN=example.com
PORTR_DB_URL=postgres://postgres:<choose-a-strong-secret>@postgres:5432/postgres

PORTR_SERVER_URL=https://example.com
PORTR_SSH_URL=example.com:2222
PORTR_AUTO_MIGRATE=true
PORTR_RESERVED_SUBDOMAIN_LIMIT=3

PORTR_SSH_HOST_KEY= # PEM-encoded Ed25519 private key

CLOUDFLARE_API_TOKEN=

POSTGRES_USER=postgres
POSTGRES_PASSWORD=<choose-a-strong-secret>
POSTGRES_DB=postgres

Environment Variable Reference

If you run on SQLite instead of PostgreSQL, see SQLite Backups for the LITESTREAM_* variables that replicate the database to object storage.

If you already run a reverse proxy or manage TLS certificates manually, see Custom Reverse Proxy — the Cloudflare token is only needed by the bundled Caddy service.

Generate SSH Host Key

Generate an Ed25519 private key and set it as an environment variable:

ssh-keygen -t ed25519 -f /tmp/portr_host_key -N ""
export PORTR_SSH_HOST_KEY="$(cat /tmp/portr_host_key)"
rm /tmp/portr_host_key /tmp/portr_host_key.pub

Or use portrd to generate and print a key:

portrd generate-host-key

Start the services

Run the following command to start all services:

docker compose -f docker-compose.prod.yaml up -d

The server container runs as a non-root user. If you keep the default ./data bind mount, make sure that directory is writable by the container user before starting the service.

Access the admin dashboard

Once the servers are running, navigate to your domain (e.g., https://example.com) and log in to the admin dashboard. The first login will be treated as a superuser account.

Alternative Database Setup

Troubleshooting

Service Health Checks

Check if all services are running properly:

docker compose -f docker-compose.prod.yaml ps

View Service Logs

Check logs for any specific service:

# View all logs
docker compose -f docker-compose.prod.yaml logs

# View logs for a specific service
docker compose -f docker-compose.prod.yaml logs server
docker compose -f docker-compose.prod.yaml logs caddy
docker compose -f docker-compose.prod.yaml logs postgres

SSL Certificate Issues

If you're having SSL certificate issues, ensure:

1. Your DNS records are properly configured
2. Your Cloudflare API token has the correct permissions
3. Your domain is added to Cloudflare

Port Accessibility

Verify that the required ports are accessible:

# Check if port 2222 is accessible
telnet your-domain.com 2222

# Check if HTTP/HTTPS ports are working
curl https://your-domain.com