Deploying with Docker

This guide takes you from a first container through to the settings worth having in place before you put Portway in front of real traffic, whether that is a laptop, a Home Lab, or a production host. Before you begin, make sure Docker is installed and running.

If you would rather host on Windows Server behind IIS, Deploying on Windows Server covers that path.

Quick start ​

If you have not started a container yet, Getting Started has a minimal docker-compose.yml you can copy and run in a couple of minutes. Once it is up, the API is available at http://localhost:8080.

The rest of this page picks up from there, covering the settings you are most likely to reach for next.

Configuration ​

Environment variables ​

The Docker Compose configuration can be extended with additional environment variables for advanced functionality:

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:
      # Set your environment variables here
      - PORTWAY_ENCRYPTION_KEY=YourEncryptionKeyHere
      - AllowedHosts=*
      - PathBase=

      # Web UI settings
      - WebUi__AdminApiKey=INSECURE-CHANGE-ME-admin-api-key
      - WebUi__PublicOrigins__0=https://example.com
      - WebUi__PublicOrigins__1=https://api.example.com
      - WebUi__SecureCookies=false  
      - WebUi__Customization__PromoText=
      - WebUi__Customization__LoginFooter=If you don't have an account, please contact your [administrator](mailto:support@democompany.local).
    
      # Proxy settings for Kerberos/NTLM
      # - PROXY_USERNAME=serviceaccount
      # - PROXY_PASSWORD=password
      # - PROXY_DOMAIN=YOURDOMAIN

      # Azure credentials
      # - 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
    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 ​

Web UI settings ​

For WebUi__PublicOrigins, use index notation for multiple origins:

- WebUi__PublicOrigins__0=https://example.com
- WebUi__PublicOrigins__1=https://api.example.com

Proxy configuration ​

Configure these settings if your environment requires proxy authentication. Portway supports NTLM authentication for corporate proxy environments:

Azure Key Vault (optional) ​

For production environments, you can integrate with Azure Key Vault by uncommenting and configuring:

Data persistence ​

The Docker Compose setup includes volume mounts for data persistence:

volumes:
  - ./environments:/app/environments
  - ./endpoints:/app/endpoints
  - ./tokens:/app/tokens
  - ./log:/app/log
  - ./data:/app/data

• Configuration files: environments/, endpoints/, and tokens/ are bind-mounted so you can edit them from the host
• Logs: written to ./log, including the traffic log database at log/traffic_logs.db
• Databases: auth.db, metrics.db, and mcp.db are created at the application root, so they live in the portway_app named volume rather than a bind mount

Customizing the setup ​

Custom configuration ​

1. Create your configuration files in the mounted directories:

   • ./endpoints/ - API endpoint definitions
   • ./environments/ - Environment configurations
   • ./tokens/ - Authentication tokens

2. Restart the container to apply changes:

   bash

   docker compose restart

Managing tokens ​

Token management is handled through the Web UI. Set WebUi__AdminApiKey in your environment configuration to enable it, then navigate to http://localhost:8080/ui and open Tokens to create, revoke, rotate, and audit tokens.

environment:
  - WebUi__AdminApiKey=your-secure-password

Going to production ​

The compose file above is deliberately minimal. A few additions are worth making before real traffic arrives.

Set the encryption key ​

PORTWAY_ENCRYPTION_KEY protects the connection strings in your environment settings. Generate one and keep it out of the compose file itself, for example in a .env file or your secrets manager:

openssl rand -base64 48

Terminate TLS in front of the container ​

Portway serves plain HTTP inside the container. Put a reverse proxy (nginx, Traefik, Caddy) in front of it to terminate TLS, or publish it behind an ingress that does.

Back up your state ​

Your configuration lives in the bind mounts, and the databases live in the portway_app volume. Data Persistence above lists exactly what sits where, and a backup wants both.

Watch it ​

Health endpoints and Prometheus metrics are described in Monitoring, and Security covers token scoping, rate limiting, and network restrictions.

For upgrades, see Upgrading Portway.

Next steps ​

After successful installation:

1. Review the Getting Started Guide for basic usage
2. Configure your Endpoints
3. Set up Security and authentication
4. Monitor your deployment with Health Checks