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:

.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=https://example.com
PORTR_SSH_URL=example.com:2222
PORTR_AUTO_MIGRATE=true

PORTR_SSH_HOST_KEY= # PEM-encoded Ed25519 private key

CLOUDFLARE_API_TOKEN=

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=postgres

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_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.

Start the services

Run the following command to start all services:

docker compose -f docker-compose.prod.yaml 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 -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:

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