Docker Installation

This guide explains how to deploy Portway using Docker Compose for quick development, testing and/or Home Lab environments. Before you begin, ensure you have Docker installed and running.

Quick Start ​

1. Create a docker-compose.yml file:

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

volumes:
  portway_app:

2. Start the application:

docker compose up -d

3. Verify the installation: The API will be available at http://localhost:8080

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: Mounted from local directories for easy editing
• Authentication data: Stored in the ./data directory
• Logs: Available in the ./log directory

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

Health Check ​

The container can be monitored to verify the API is responding:

# Check container health
docker compose ps

# View container logs
docker compose logs portway

Troubleshooting ​

Container Won't Start ​

1. Check Docker logs:
   bash

   docker compose logs portway

Configuration Issues ​

1. Verify environment variables are set correctly
2. Check mounted volume permissions
3. Review application logs in the ./log directory

Proxy Authentication ​

If you're behind a corporate proxy:

1. Update the proxy settings in the environment variables
2. Ensure your proxy credentials are correct
3. Contact your network administrator for proxy details

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

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

Production Considerations ​

For production deployments, see the Deployment Guide.