The config.yml file controls all aspects of your Pangolin deployment, including server settings, domain configuration, email setup, and security options. This file is mounted at config/config.yml in your Docker container.
Setting up your config.yml To get started, create a basic configuration file with the essential settings:
Minimal Pangolin configuration:
app : dashboard_url : "https://pangolin.example.com" domains : domain1 : base_domain : "pangolin.example.com" cert_resolver : "letsencrypt" server : secret : "your-strong-secret" gerbil : base_endpoint : "pangolin.example.com" flags : require_email_verification : false disable_signup_without_invite : true disable_user_create_org : true Generate a strong secret for server.secret. Use at least 32 characters with a mix of letters, numbers, and special characters.
Reference This section contains the complete reference for all configuration options in config.yml.
Application Settings Core application configuration including dashboard URL, logging, and general settings. The URL where your Pangolin dashboard is hosted. Examples : https://example.com, https://pangolin.example.comThis URL is used for generating links, redirects, and authentication flows. You can run Pangolin on a subdomain or root domain.
The logging level for the application. Options : debug, info, warn, errorDefault : info
Whether to save logs to files in the config/logs/ directory. Default : falseWhen enabled, logs rotate automatically:
Max file size: 20MB
Max files: 7 days
Whether to log failed authentication attempts for security monitoring. Default : false
Telemetry configuration settings. Whether to enable anonymous usage telemetry. Default : true
Notification configuration settings. Whether to enable showing product updates notifications on the UI. Default : true
Whether to enable showing new releases notifications on the UI. Default : true
Server Configuration Server ports, networking, and authentication settings. The port for the front-end API that handles external requests. Example : 3000
The port for the internal private-facing API. Example : 3001
The port for the frontend server (Next.js). Example : 3002
The port for the integration API (optional). Example : 3003
The hostname of the Pangolin container for internal communication. Example : pangolinIf using Docker Compose, this should match your container name.
The name of the session cookie for storing authentication tokens. Example : p_session_tokenDefault : p_session_token
resource_access_token_param
Query parameter name for passing access tokens in requests. Example : p_tokenDefault : p_token
HTTP headers for passing access tokens in requests. Header name for access token ID. Example : P-Access-Token-Id
Header name for access token. Example : P-Access-Token
resource_session_request_param
Query parameter for session request tokens. Example : p_session_requestDefault : p_session_request
Cross-Origin Resource Sharing (CORS) configuration. Allowed origins for cross-origin requests. Example : ["https://pangolin.example.com"]
Allowed HTTP methods for CORS requests. Example : ["GET", "POST", "PUT", "DELETE", "PATCH"]
Allowed HTTP headers in CORS requests. Example : ["X-CSRF-Token", "Content-Type"]
Whether to allow credentials in CORS requests. Default : true
Number of proxy headers to trust for client IP detection. Example : 1Default : 1Use 1 if running behind a single reverse proxy like Traefik.
dashboard_session_length_hours
Dashboard session duration in hours. Example : 720 (30 days)Default : 720
resource_session_length_hours
Resource session duration in hours. Example : 720 (30 days)Default : 720
Secret key for encrypting sensitive data. Environment Variable : SERVER_SECRETMinimum Length : 8 charactersExample : "[email protected] _A@9b3y"Generate a strong, random secret. This is used for encrypting sensitive data and should be kept secure.
Path to the MaxMind GeoIP database file for geolocation features. Example : ./config/GeoLite2-Country.mmdbUsed for IP geolocation functionality. Requires a MaxMind GeoLite2 or GeoIP2 database file.
Domain Configuration Domain settings for SSL certificates and routing. At least one domain must be configured. It is best to add it in the UI for ease of use or when you want the
domain to only be present in the org it was created in . You should create it in the config file for permanence across installs
and if you want the domain to be present in all orgs. Domain configuration with a unique key of your choice. The base domain for this configuration. Example : example.com
The Traefik certificate resolver name. Example : letsencryptThis must match the certificate resolver name in your Traefik configuration.
Whether to prefer wildcard certificates for this domain. Example : trueUseful for domains with many subdomains to reduce certificate management overhead.
Traefik Integration Traefik reverse proxy configuration settings. The Traefik entrypoint name for HTTP traffic. Example : webMust match the entrypoint name in your Traefik configuration.
The Traefik entrypoint name for HTTPS traffic. Example : websecureMust match the entrypoint name in your Traefik configuration.
The default certificate resolver for domains created through the UI. Example : letsencryptThis only applies to domains created through the Pangolin dashboard.
Whether to prefer wildcard certificates for UI-created domains. Example : trueThis only applies to domains created through the Pangolin dashboard.
Additional Traefik middlewares to apply to resource routers. Example : ["middleware1", "middleware2"]These middlewares must be defined in your Traefik dynamic configuration.
Path where SSL certificates are stored. This is used only with managed Pangolin deployments. Example : /var/certificatesDefault : /var/certificates
Interval in milliseconds for monitoring configuration changes. Example : 5000Default : 5000
Path to the dynamic certificate configuration file. This is used only with managed Pangolin deployments. Example : /var/dynamic/cert_config.ymlDefault : /var/dynamic/cert_config.yml
dynamic_router_config_path
Path to the dynamic router configuration file. Example : /var/dynamic/router_config.ymlDefault : /var/dynamic/router_config.yml
Supported site types for Traefik configuration. Example : ["newt", "wireguard", "local"]Default : ["newt", "wireguard", "local"]
Whether to use file-based configuration mode for Traefik. Example : falseDefault : falseWhen enabled, uses file-based dynamic configuration instead of API-based updates.
Prefix used for transport-related configurations. References servers transport config in dynamic Traefik file. Example : pp-transport-vDefault : pp-transport-v
Gerbil Tunnel Controller Gerbil tunnel controller settings for WireGuard tunneling. Domain name included in WireGuard configuration for tunnel connections. Example : pangolin.example.com
Starting port for WireGuard tunnels. Example : 51820
Whether to assign unique subdomains to Gerbil exit nodes. Default : falseKeep this set to false for most deployments.
IP address CIDR range for Gerbil exit node subnets. Example : 10.0.0.0/8
Block size for Gerbil exit node CIDR ranges. Example : 24
Block size for site CIDR ranges connected to Gerbil. Example : 26
Organization Settings Organization network configuration settings. Block size for organization CIDR ranges. Example : 24Default : 24Determines the subnet size allocated to each organization for network isolation.
IP address CIDR range for organization subnets. Example : 100.90.128.0/24Default : 100.90.128.0/24Base subnet from which organization-specific subnets are allocated.
Rate Limiting Rate limiting configuration for API requests. Global rate limit settings for all external API requests. Time window for rate limiting in minutes. Example : 1
Maximum number of requests allowed in the time window. Example : 100
Rate limit settings specifically for authentication endpoints. Time window for authentication rate limiting in minutes. Example : 1Default : 1
Maximum number of authentication requests allowed in the time window. Example : 10Default : 500Consider setting this lower than global limits for security.
Email Configuration SMTP settings for sending transactional emails. SMTP server hostname. Example : smtp.gmail.com
SMTP server port. Example : 587 (TLS) or 465 (SSL)
SMTP password. Environment Variable : EMAIL_SMTP_PASS
Whether to use secure connection (SSL/TLS). Default : falseEnable this when using port 465 (SSL).
From address for sent emails. Example : [email protected] Usually the same as smtp_user.
smtp_tls_reject_unauthorized
Whether to fail on invalid server certificates. Default : true
Feature Flags Feature flags to control application behavior. require_email_verification
Whether to require email verification for new users. Default : falseOnly enable this if you have email configuration set up.
disable_signup_without_invite
Whether to disable public user registration. Default : falseUsers can still sign up with valid invites when enabled.
Whether to prevent users from creating organizations. Default : falseServer admins can always create organizations.
Whether to allow raw TCP/UDP resource creation. Default : trueIf set to false, users will only be able to create http/https resources.
Whether to enable the integration API. Default : false
Whether to disable local site creation and management. Default : falseWhen enabled, users cannot create sites that connect to local networks.
disable_basic_wireguard_sites
Whether to disable basic WireGuard site functionality. Default : falseWhen enabled, only advanced WireGuard configurations are allowed.
disable_config_managed_domains
Whether to disable domains managed through the configuration file. Default : falseWhen enabled, only domains created through the UI are allowed.
Whether to enable client functionality. Default : trueControls access to client-related features and endpoints.
Database Configuration PostgreSQL database configuration (optional). PostgreSQL connection string. Example : postgresql://user:password@host:port/databaseRead-only replica database configurations for load balancing. Show Replica Configuration
Connection string for the read replica database. Example : postgresql://user:password@replica-host:port/database
Database connection pool settings. Maximum number of connections to the primary database. Default : 20Example : 50
Maximum number of connections to replica databases. Default : 10Example : 25
Time in milliseconds before idle connections are closed. Default : 30000 (30 seconds)Example : 60000
Time in milliseconds to wait for a database connection. Default : 5000 (5 seconds)Example : 10000
DNS Configuration DNS settings for domain name resolution and CNAME extensions. List of nameservers used for DNS resolution. Example : ["ns1.example.com", "ns2.example.com"]Default : ["ns1.pangolin.net", "ns2.pangolin.net", "ns3.pangolin.net"]These nameservers are used for DNS queries and domain resolution.
Domain extension used for CNAME record management. Example : cname.example.comDefault : cname.pangolin.netUsed for creating CNAME records for dynamic domain routing.
Environment Variables Some configuration values can be set using environment variables for enhanced security:
Name Variable Config Server Secret SERVER_SECRETserver.secretEmail Password EMAIL_SMTP_PASSemail.smtp_passPostgreSQL Connection String POSTGRES_CONNECTION_STRINGpostgres.connection_string
