Deploying with Docker

Requires Docker. Windows Server: Deploying on Windows Server.

Quick start ​

A minimal docker-compose.yml is in Getting Started. The API listens on http://localhost:8080.

Configuration ​

Environment variables ​

Compose file with the environment variables:

services:
  portway:
    image: ghcr.io/melosso/portway:latest
    ports:
      - "8080:8080"
    volumes:
      - portway_app:/app
      - ./environments:/app/environments
      - ./endpoints:/app/endpoints
      - ./tokens:/app/tokens
      - ./log:/app/log
      - ./data:/app/data
    environment:
      - PORTWAY_ENCRYPTION_KEY=YourEncryptionKeyHere
      - PORTWAY_PUBLIC_ORIGINS=https://example.com,https://api.example.com
      - PORTWAY_SECURE_COOKIES=false # true behind TLS
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health/live"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
      
volumes:
  portway_app:

Core settings ​

Legacy names remain supported with a deprecation warning at startup; the PORTWAY_* name takes precedence.

Web UI settings ​

Banner and sign-in footer settings are set under Settings in the console. Environment variables lists every PORTWAY_* name. A setting with a set environment variable is read-only in the console.

Proxy configuration ​

Credentials for outbound requests through an authenticating (NTLM) corporate proxy:

    environment:
      - PORTWAY_PROXY_USERNAME=serviceaccount
      - PORTWAY_PROXY_PASSWORD=password
      - PORTWAY_PROXY_DOMAIN=YOURDOMAIN

Azure Key Vault (optional) ​

The AZURE_* variables are read by the Azure SDK's DefaultAzureCredential.

    environment:
      - PORTWAY_KEYVAULT_URI=https://your-keyvault-name.vault.azure.net/
      - AZURE_CLIENT_ID=your-client-id
      - AZURE_TENANT_ID=your-tenant-id
      - AZURE_CLIENT_SECRET=your-client-secret

Data persistence ​

An environment variable overrides the same setting in appsettings.overrides.json. The console displays that setting as read-only. Leave a variable unset to manage the setting from the console.

appsettings.overrides.json can also be bind-mounted as a single file. Create the file with the content {} before the first start. Docker creates a directory for a missing bind-mount source.

Customizing the setup ​

Endpoint and environment files in the mounted directories are reloaded on change. Other configuration changes apply after a restart:

docker compose restart

Managing tokens ​

Tokens are managed in the console at http://localhost:8080/ui under Access Tokens.

Going to production ​

Set the encryption key ​

The PORTWAY_ENCRYPTION_KEY value encrypts secrets in environment settings. Keep it out of the compose file, e.g. in a .env file or a secrets manager:

openssl rand -base64 48

$bytes = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
[Convert]::ToBase64String($bytes)

Terminate TLS in front of the container ​

The container serves plain HTTP. TLS terminates at a reverse proxy (nginx, Traefik, Caddy) or ingress.

Backups ​

Back up the bind mounts and the portway_app volume (Data persistence). Portway also writes a daily snapshot of its databases and configuration to .backups/snapshots/ (DatabaseMaintenance).

Monitoring ​

Health endpoints: Health and Logs. Metrics: Telemetry. Upgrades: Upgrading Portway.

Next steps ​

• Getting Started
• SQL Endpoints
• Security
• Health and Logs