Getting Started

Portway is an ASP.NET Core application. It runs as a Docker container, on Windows Server behind IIS, or standalone on Kestrel.

Prerequisites ​

Docker ​

• Docker Engine with Compose support

Windows Server / IIS ​

• Windows Server (or Windows 11 for development)
• .NET 11 ASP.NET Core Hosting Bundle
• Internet Information Services (IIS)

Installation ​

Docker Compose ​

Minimal compose 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:

Start:

docker compose pull && docker compose up -d

Portway listens on port 8080. Configuration options: Deploying with Docker.

Windows Server (IIS) ​

1. Download the latest release from the Releases page.
2. Install the .NET 11 ASP.NET Core Hosting Bundle.
3. Set a machine-level PORTWAY_ENCRYPTION_KEY.
4. Create an IIS site for the extracted folder with an application pool set to No Managed Code.

Key generation, application pool settings, NTLM pass-through and backups: Deploying on Windows Server.

Initial configuration ​

Retrieve your access token ​

The first start generates an access token and writes it to:

tokens/YOUR_SERVER_NAME.txt

File contents:

{
  "Username": "SERVER-NAME",
  "Token": "your-bearer-token-here",
  "AllowedScopes": "*",
  "AllowedEnvironments": "*",
  "ExpiresAt": "Never",
  "CreatedAt": "2025-01-01 00:00:00"
}

Configure environments ​

Routable environments are listed in environments/settings.json:

{
  "Environment": {
    "ServerName": "localhost",
    "AllowedEnvironments": ["dev", "test", "prod"]
  }
}

Each environment has a folder with its own settings.json:

environments/
  ├── settings.json
  ├── dev/
  │   └── settings.json
  ├── test/
  │   └── settings.json
  └── prod/
      └── settings.json

Example environments/prod/settings.json:

{
  "ServerName": "SQLSERVER01",
  "ConnectionString": "Server=SQLSERVER01;Database=ProductionDB;Trusted_Connection=True;TrustServerCertificate=true;",
  "Headers": {
    "Origin": "Portway"
  }
}

Create your first endpoint ​

An endpoint is a JSON file, e.g. endpoints/SQL/Products/entity.json:

{
  "DatabaseObjectName": "Products",
  "DatabaseSchema": "dbo",
  "PrimaryKey": "ProductId",
  "AllowedColumns": [
    "ProductId",
    "ProductName",
    "Price",
    "Stock"
  ],
  "AllowedEnvironments": ["dev", "test", "prod"]
}

New and changed endpoint files are loaded without a restart.

Test your API ​

The API reference at https://localhost/docs accepts the Bearer token for test calls:

GET /api/prod/Products
Authorization: Bearer YOUR_ACCESS_TOKEN

Next steps ​

• Configure SQL Endpoints
• Set up Proxy Endpoints
• Manage Environments
• Configure Security