Application Settings

When you want to shape how Portway behaves at its core (logging, security, rate limiting, and service wiring), appsettings.json is where you'll spend your time. This page walks through each section, explains what it controls, and shows how you can override values per deployment without touching the base file.

Configuration files ​

Core configuration structure ​

{
  "AllowedHosts": "*",
  "PathBase": "",
  "WebUi": { ... },
  "OpenApi": { ... },
  "RateLimiting": { ... },
  "ForwardedHeaders": { ... },
  "RequestTrafficLogging": { ... },
  "SqlConnectionPooling": { ... },
  "Caching": { ... },
  "FileStorage": { ... },
  "Telemetry": { ... },
  "Mcp": { ... },
  "EndpointReloading": { ... },
  "Serilog": { ... }
}

Each section is described below.

Logging configuration ​

Portway uses Serilog for structured logging with configurable sinks and filtering.

Basic structure ​

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.EntityFrameworkCore.Database.Command": "Warning",
        "System": "Warning",
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "Console"
      },
      {
        "Name": "File",
        "Args": {
          "path": "log/portwayapi-.log",
          "rollingInterval": "Day",
          "fileSizeLimitBytes": 10485760,
          "rollOnFileSizeLimit": true,
          "retainedFileCountLimit": 10,
          "buffered": true,
          "flushToDiskInterval": "00:00:30"
        }
      }
    ]
  }
}

Serilog replaces the standard .NET logging factory here, so the Serilog section is the only one that shapes output. A Logging section, if you add one, is read by nothing.

Changing log levels ​

To change the logging level, modify the Default value in appsettings.json:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug"  // Change to Debug, Information, Warning, Error, or Fatal
    }
  }
}

Serilog owns the effective level, so this is the setting that changes what reaches the console and the log files. What each level covers, along with rotation, retention and structured output, is described in Logging.

OpenAPI configuration ​

The OpenApi section controls the generated API documentation and the Scalar UI that renders it.

{
  "OpenApi": {
    "Enabled": true,
    "Title": "Portway: API Gateway",
    "Version": "v1"
  }
}

Every property, including the contact block, security definition and the full set of Scalar display options, is listed in OpenAPI settings.

Rate limiting configuration ​

The RateLimiting section sets the per-IP and per-token request budgets.

{
  "RateLimiting": {
    "Enabled": true,
    "IpLimit": 100,
    "IpWindow": 60,
    "TokenLimit": 1000,
    "TokenWindow": 60,
    "Store": "Memory"
  }
}

For the property reference, per-token overrides, Redis-backed buckets and tuning advice, see Rate limiting.

Forwarded headers ​

When Portway runs directly on Kestrel, the client IP it sees is the one connecting to it, which is exactly what per-IP rate limiting and the Web UI network gate rely on. Once you place a reverse proxy in front (nginx, IIS, or similar), that connecting IP becomes the proxy instead, and every client starts to look like the same address. The real client IP is still available in the X-Forwarded-For header, and this section is how you tell Portway which proxies it can trust to set it.

Configuration structure ​

{
  "ForwardedHeaders": {
    "KnownProxies": ["127.0.0.1", "::1"],
    "KnownNetworks": ["10.0.0.0/8"]
  }
}

Property reference ​

How it works ​

Portway only honors X-Forwarded-For when the request arrives from an address you have listed here, which keeps clients from spoofing their own IP. You can register individual proxy addresses in KnownProxies, describe a whole range in KnownNetworks, or combine both when your setup calls for it. A common starting point for a proxy sharing the host with Portway is 127.0.0.1 and ::1.

Leaving both lists empty is perfectly valid, and it is the default. In that case X-Forwarded-For is ignored entirely and the connecting address is used as-is. That is the safe choice when nothing sits in front of Portway, though behind a proxy it means per-IP rate limiting, the console sign-in lockout, and the network-based Web UI gate will all see the proxy rather than the real caller. If you rely on any of those, registering your proxy here is recommended.

The Web UI shows which of the two applies. Open Settings → Security and read the Client addresses row: it gives the client address Portway saw for your request, and warns when a forwarded address arrived with no proxy trusted to send it. Add the proxy from Deployment & Access on the same page.

The Settings posture panel in the Web UI reflects whether any trusted proxies are configured, which is a quick way to confirm the setup took effect.

Request traffic logging ​

The RequestTrafficLogging section records every proxied request to file or SQLite. It stays off until you enable it.

{
  "RequestTrafficLogging": {
    "Enabled": false,
    "StorageType": "file"
  }
}

The full property reference, the stored record shape and retention behaviour live in Audit and traffic logging. Response bodies are captured here too: set IncludeResponseBodies, and cap what gets stored with MaxBodyCaptureSizeBytes.

SQL connection pooling ​

Configuration structure ​

{
  "SqlConnectionPooling": {
    "ApplicationName": "Portway API - Remote integration gateway",
    "MinPoolSize": 5,
    "MaxPoolSize": 100,
    "ConnectionTimeout": 15,
    "CommandTimeout": 30,
    "Enabled": true
  }
}

Property reference ​

Caching configuration ​

The Caching section controls response caching for proxy and SQL endpoints, backed by memory or Redis.

{
  "Caching": {
    "Enabled": true,
    "DefaultCacheDurationSeconds": 300,
    "ProviderType": "Memory"
  }
}

The property reference, the Redis block and per-endpoint duration overrides are documented in Caching.

File storage configuration ​

Controls how Portway stores and serves files for File-type endpoints.

Configuration structure ​

{
  "FileStorage": {
    "StorageDirectory": "storage/files",
    "MaxFileSizeBytes": 52428800,
    "UseMemoryCache": true,
    "MemoryCacheTimeSeconds": 60,
    "MaxTotalMemoryCacheMB": 200,
    "BlockedExtensions": [".exe", ".dll", ".bat", ".sh", "..."]
  }
}

Property reference ​

Endpoint reloading configuration ​

Controls hot-reload behaviour when endpoint JSON files change on disk.

Configuration structure ​

{
  "EndpointReloading": {
    "Enabled": true,
    "DebounceMs": 2000
  }
}

Property reference ​

Telemetry ​

Controls how request traces and metrics leave the gateway. Telemetry is off by default; selecting a provider activates it.

"Telemetry": {
  "Provider": "Otlp",
  "ServiceName": "portway-prod",
  "ResourceAttributes": "deployment.environment=production,host.name=gw01",
  "Otlp": {
    "Endpoint": "http://otel-collector.internal:4317"
  },
  "Prometheus": {
    "Path": "/metrics"
  }
}

The Otlp provider pushes traces and metrics to a collector over gRPC; the Prometheus provider serves metrics on a scrape endpoint instead. Configurations from earlier releases keep working: a flat "Enabled": true selects the OTLP provider, and a flat OtlpEndpoint is used whenever Otlp:Endpoint is not set. See the Telemetry guide for the full walkthrough.

MCP configuration ​

The Mcp section exposes endpoints as Model Context Protocol tools.

{
  "Mcp": {
    "Enabled": false,
    "Path": "/mcp",
    "RequireAuthentication": true
  }
}

The property reference, per-endpoint exposure and the built-in tools are covered in the MCP server guide.

General settings ​

AllowedHosts ​

{
  "AllowedHosts": "*"
}

Configure which hosts can access the application:

• "*" - Allow all hosts
• "example.com" - Allow specific domain
• "*.example.com" - Allow subdomains
• "example.com;api.example.com" - Multiple hosts

PathBase ​

{
  "PathBase": ""
}

Base path for the application (e.g., /api).

Web UI configuration ​

The built-in admin interface settings.

{
  "WebUi": {
    "AdminApiKey": "your-secure-password",
    "PublicOrigins": ["https://example.com"],
    "SecureCookies": true,
    "Customization": {
      "EnableLandingPage": true
    }
  }
}

Property reference ​

Security ​

• Portway asks for a sign-in as soon as one console account exists. AdminApiKey only creates that first account, so you can clear it once you can sign in
• Without PublicOrigins, only local network IPs can access the UI
• PublicOrigins is matched against the request's Origin header, which any client can set. It widens who can reach the sign-in page; it does not authenticate anyone. Keep the console behind your proxy, VPN, or firewall when it should not be public
• Cookie auth uses HMAC-SHA256 signing
• Set Customization.EnableLandingPage to false on internet-facing or production deployments to prevent the admin UI from being surfaced at the root path

Customization example ​

{
  "WebUi": {
    "Customization": {
      "PromoText": "Welcome to **Portway**. Check the [documentation](https://github.com/melosso/portway) to get started.",
      "LoginFooter": "No account? Contact your [administrator](mailto:admin@example.com)."
    }
  }
}

Both fields support standard Markdown (bold, links, inline code).

Environment-Specific configuration ​

Development settings ​

appsettings.Development.json:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft.EntityFrameworkCore.Database.Command": "Information"
      }
    }
  },
  "RequestTrafficLogging": {
    "Enabled": true,
    "IncludeRequestBodies": true,
    "IncludeResponseBodies": true
  }
}

Production settings ​

appsettings.Production.json:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Warning",
      "Override": {
        "PortwayApi": "Information"
      }
    }
  },
  "RateLimiting": {
    "IpLimit": 200,
    "TokenLimit": 1000
  },
  "AllowedHosts": "api.company.com"
}

Security settings ​

Host filtering and CORS ​

These are two separate controls, and it helps to keep them apart.

AllowedHosts filters on the Host header of incoming requests. The default "*" accepts any host, and you can narrow it to the names you serve:

{
  "AllowedHosts": "api.company.com;app.company.com"
}

Browser cross-origin access is governed by WebUi:CorsOrigins instead, which is an explicit allowlist of origins. Web UI settings covers it along with PublicOrigins, which controls who may reach the admin interface from outside the local network.

Turning features off ​

Each of these turns off one subsystem and leaves its configuration in place:

Portway reads Oidc:Enabled on each request, so a change applies without a restart and the provider records stay as they are. Single sign-on covers the providers.

Set any of these from Settings → Security → Feature Toggles in the console, or in appsettings.json.

Environment variables ​

Common variables ​

Configuration priority ​

1. Environment variables
2. appsettings.{Environment}.json
3. appsettings.json
4. Default values

Troubleshooting configuration ​

Configuration debugging ​

1. Enable detailed logging. Serilog sets the effective level, so lower Serilog:MinimumLevel rather than the Logging section:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Information"
      }
    }
  }
}

2. Check environment variable:

$env:ASPNETCORE_ENVIRONMENT

echo $ASPNETCORE_ENVIRONMENT

3. Review startup logs for configuration issues

A complete file to start from ​

The appsettings.json that ships with Portway is the working reference: it carries every section above with its default value, so you can read it as the canonical example. Rather than replacing it wholesale, keep it as your base and put deployment-specific values in appsettings.Production.json, as shown in Environment-Specific configuration.

Related topics ​

• Environment Settings
• Security Guide
• Deployment Guide
• Logging