Environment Settings

Environment settings control database connections, allowed environments, and environment-specific configurations. These settings ensure proper isolation between development, testing, and production environments.

File Structure ​

Environment configuration files are organized in the following structure:

/environments/
  ├── [EnvironmentName]/             # Environment-specific folders
  │   └── settings.json              # Environment-specific settings
  ├── settings.json                  # Global settings
  └── network-access-policy.json     # Network security policy

Global Settings ​

The root settings.json file defines which environments are allowed:

File Location ​

/environments/settings.json

Configuration Structure ​

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

Property Reference ​

Environment-Specific Settings ​

Each environment has its own configuration file with connection details:

File Location ​

/environments/[EnvironmentName]/settings.json

Basic Configuration ​

{
  "ServerName": "SERVERNAME",
  "ConnectionString": "Server=SERVERNAME;Database=prod;Trusted_Connection=True;Connection Timeout=15;TrustServerCertificate=true;",
  "Headers": {
    "DatabaseName": "prod",
    "ServerName": "SERVERNAME",
    "Origin": "Portway"
  }
}

Property Reference ​

Headers Configuration ​

Custom headers added to all requests for this environment:

Network Access Policy ​

Controls which hosts and IP ranges are allowed for proxy requests:

File Location ​

/environments/network-access-policy.json

Configuration Structure ​

{
  "allowedHosts": [
    "localhost",
    "127.0.0.1"
  ],
  "blockedIpRanges": [
    "10.0.0.0/8",
    "172.16.0.0/12",
    "192.168.0.0/16",
    "169.254.0.0/16"
  ]
}

Property Reference ​

Examples ​

Production Environment ​

/environments/prod/settings.json

{
  "ServerName": "SQLPROD01",
  "ConnectionString": "Server=SQLPROD01;Database=ProductionDB;User Id=svc_portway;Password=${PROD_DB_PASSWORD};Connection Timeout=30;TrustServerCertificate=false;Encrypt=true;",
  "Headers": {
    "DatabaseName": "ProductionDB",
    "ServerName": "SQLPROD01",
    "Environment": "Production",
    "X-Strict-Mode": "true"
  }
}

Development Environment ​

/environments/dev/settings.json

{
  "ServerName": "SQLDEV01",
  "ConnectionString": "Server=SQLDEV01;Database=DevelopmentDB;Trusted_Connection=True;Connection Timeout=15;TrustServerCertificate=true;",
  "Headers": {
    "DatabaseName": "DevelopmentDB",
    "ServerName": "SQLDEV01",
    "Environment": "Development",
    "X-Debug-Mode": "true"
  }
}

Connection String Configuration ​

The ConnectionString value determines both the target database and the SQL driver Portway uses. No additional property is needed, the provider is detected automatically.

See the SQL Providers reference for the full detection algorithm and capability differences between providers.

SQL Server: Windows authentication ​

{
  "ConnectionString": "Server=SERVER;Database=DB;Trusted_Connection=True;Connection Timeout=15;TrustServerCertificate=true;"
}

SQL Server: SQL authentication ​

{
  "ConnectionString": "Server=SERVER;Database=DB;User Id=username;Password=password;Connection Timeout=30;TrustServerCertificate=false;Encrypt=true;"
}

PostgreSQL ​

{
  "ConnectionString": "Host=db.example.com;Port=5432;Database=mydb;Username=portway;Password=your-password;"
}

MySQL / MariaDB ​

{
  "ConnectionString": "Server=db.example.com;Port=3306;Database=mydb;Uid=portway;Pwd=your-password;SslMode=Preferred;"
}

SQLite ​

{
  "ConnectionString": "Data Source=environments/WMS/demo.db;"
}

Paths are resolved relative to the Portway application working directory. SQLite connection strings carry no credentials and are not subject to automatic encryption or masking.

Key parameters by provider ​

SQL Server

PostgreSQL

MySQL / MariaDB

SQLite

Variables ​

Sensitive values can use environment variables:

{
  "ConnectionString": "Server=SQLPROD;Database=ProdDB;User Id=svc_portway;Password=${PROD_DB_PASSWORD};"
}

Supported variables:

• ${VARIABLE_NAME} - Replaced at runtime
• Azure Key Vault integration (if configured)

Security Notes ​

The network access policy in network-access-policy.json prevents Server-Side Request Forgery (SSRF) by blocking private IP ranges and restricting proxy target hosts. Use separate database credentials per environment, and set Encrypt=true; TrustServerCertificate=false on production SQL Server connections.

Troubleshooting ​

Common Issues ​

1. Environment Not Found

   • Check environment name in AllowedEnvironments
   • Verify folder structure: /environments/[name]/settings.json
   • Ensure correct file permissions

2. Database Connection Failed

   • Test connection string with SQL tools
   • Verify server name and database
   • Check firewall rules
   • Validate credentials

3. Headers Not Applied

   • Confirm headers in environment settings
   • Check for typos in header names
   • Verify environment is selected correctly

4. Network Access Denied

   • Review allowed hosts list
   • Check if IP is in blocked ranges
   • Validate DNS resolution
   • Test with diagnostic tools

Related Topics ​

• Entity Configuration - Endpoint configuration
• Security Guide - Security best practices
• Deployment Guide - Production deployment
• Application Settings - Application configuration