Deploying

This guide walks you through deploying Portway on Windows Server behind IIS, from prerequisites to a running gateway with a backup routine. If you're deploying with containers instead, Docker Installation covers that path.

The steps assume working knowledge of IIS and your network and data sources; the essentials are all here, though some details will depend on your existing environment.

Prerequisites ​

• Windows Server with IIS installed and running
• Administrator access
• ASP.NET Core 10 Hosting Bundle
• A TLS/SSL certificate (self-signed is acceptable for internal deployments)

Installation ​

1. Generate the encryption key ​

Set the encryption key as a Machine-level environment variable before deploying the application files:

$bytes = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
[Environment]::SetEnvironmentVariable("PORTWAY_ENCRYPTION_KEY", [Convert]::ToBase64String($bytes), "Machine")

2. Deploy application files ​

Extract the Portway release to your target directory (e.g. C:\Apps\Portway).

3. Configure IIS ​

1. Open IIS Manager
2. Create an Application Pool:
   • Name: PortwayAppPool
   • .NET CLR version: No Managed Code
   • Pipeline mode: Integrated
   • Start Mode: AlwaysRunning
   • Idle Time-out: 0
3. Create a new Website:
   • Application pool: PortwayAppPool
   • Physical path: C:\Apps\Portway
   • HTTPS binding with your certificate
4. Set directory permissions:
   cmd

   icacls "C:\Apps\Portway" /grant "IIS AppPool\PortwayAppPool:(OI)(CI)M" /T

4. Start and verify ​

Start the website. On first run, Portway creates tokens/, log/, and auth.db automatically.

Verify the application is running:

• https://localhost/health/live, returns Alive
• https://localhost/docs, OpenAPI documentation interface

Initial configuration ​

Retrieve the access token ​

Find the generated token at tokens/[SERVERNAME].txt:

{
  "Username": "SERVER-NAME",
  "Token": "your-bearer-token-here",
  "AllowedScopes": "*",
  "AllowedEnvironments": "*"
}

Configure environments ​

Edit environments/settings.json:

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

Create environments/{name}/settings.json for each environment:

ProductionDevelopment

json

{
  "ServerName": "YOUR_SQL_SERVER",
  "ConnectionString": "Server=YOUR_SQL_SERVER;Database=prod;Trusted_Connection=True;TrustServerCertificate=true;"
}

json

{
  "ServerName": "YOUR_SQL_SERVER",
  "ConnectionString": "Server=YOUR_SQL_SERVER;Database=dev;Trusted_Connection=True;TrustServerCertificate=true;"
}

Troubleshooting ​

Enable stdout logging in web.config for startup errors that do not reach the application log:

<aspNetCore stdoutLogEnabled="true" stdoutLogFile=".\log\stdout" />

Log locations:

• Application log: log/portwayapi-*.log
• IIS log: C:\inetpub\logs\LogFiles\W3SVC[ID]\
• Startup errors: Windows Event Viewer → Application

Security configuration ​

• Enforce HTTPS using URL Rewrite rules (IIS Rewrite Module)
• Restrict tokens/ directory read access to the application pool identity only
• Configure IP whitelisting in IIS Manager (IP Address and Domain Restrictions)
• Use a dedicated domain service account with minimum SQL permissions for proxy endpoints

See Security for the full security configuration reference.

Backup ​

Include these in your backup plan:

• auth.db for authentication database
• tokens/ for token files
• environments/ for connection strings and settings
• endpoints/ for endpoint definitions

For upgrades, see Upgrading Portway.

Next steps ​

• Configure Environments
• Configure Endpoints
• Security
• Monitoring