Server Deployment

For quick setup, use the docker-compose.yml from the Portr repository:

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

Services Overview

The compose file includes 4 services:

caddy: The reverse proxy for routing and SSL termination
admin: The admin server for the web dashboard
tunnel: The tunnel server for handling connections
postgres: The PostgreSQL database

Deployment Steps

Download the compose file

Download the docker-compose.yaml file 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:

.env

PORTR_ADMIN_GITHUB_CLIENT_ID= #optional
PORTR_ADMIN_GITHUB_CLIENT_SECRET= #optional

PORTR_DOMAIN=example.com
PORTR_DB_URL=postgres://postgres:postgres@postgres:5432/postgres

PORTR_SERVER_URL=example.com
PORTR_SSH_URL=example.com:2222

PORTR_SSH_HOST_KEY= # PEM-encoded Ed25519 private key

CLOUDFLARE_API_TOKEN=

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=postgres

PORTR_ADMIN_ENCRYPTION_KEY=

Environment Variable Reference

Variable	Description	Default
`PORTR_DOMAIN`	Your server domain	`localhost:8001`
`PORTR_DB_URL`	PostgreSQL connection URL	Required
`PORTR_SERVER_URL`	Public server URL for clients	`http://localhost:8001`
`PORTR_SSH_URL`	Public SSH URL for clients	`localhost:2222`
`PORTR_SSH_PORT`	SSH server port	`2222`
`PORTR_SSH_HOST_KEY`	PEM-encoded Ed25519 private key	Required
`PORTR_ADMIN_PORT`	Admin server port	`8000`
`PORTR_ADMIN_GITHUB_CLIENT_ID`	GitHub OAuth client ID	Optional
`PORTR_ADMIN_GITHUB_CLIENT_SECRET`	GitHub OAuth client secret	Optional
`PORTR_ADMIN_ENCRYPTION_KEY`	Encryption key for sensitive data	Required
`PORTR_AUTO_MIGRATE`	Auto-run database migrations	`false`
`CLOUDFLARE_API_TOKEN`	Cloudflare API token for SSL	Required

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

For Docker deployments, you can pass the key as a multi-line environment variable in your .env file or use Docker secrets.

Generate encryption key

Generate an encryption key using the following command:

python -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"

Add this key to the PORTR_ADMIN_ENCRYPTION_KEY variable in your .env file.

Start the services

Run the following command to start all services:

docker compose up -d

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

If you want to run PostgreSQL separately and not as a Docker service, you can exclude the following environment variables from your .env file:

POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_DB

Troubleshooting

Service Health Checks

Check if all services are running properly:

docker compose ps

View Service Logs

Check logs for any specific service:

# View all logs
docker compose logs

# View logs for a specific service
docker compose logs admin
docker compose logs tunnel
docker compose logs caddy

SSL Certificate Issues

If you're having SSL certificate issues, ensure:

Your DNS records are properly configured
Your Cloudflare API token has the correct permissions
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

Server Deployment

On this page