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 In managed mode:
gerbil : start_port : 51820 base_endpoint : "154.123.45.67" # REPLACE WITH YOUR IP OR DOMAIN managed : id : "he4g78wevj25msf" secret : "n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d" 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
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 : 3004
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 : "d28@a2b.2HFTe2bMtZHGneNYgQFKT2X4vm4HuXUXBcq6aVyNZjdGt6Dx-_A@9b3y"Generate a strong, random secret. This is used for encrypting sensitive data and should be kept secure.
Domain Configuration Domain settings for SSL certificates and routing. At least one domain must be configured. 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.
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
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
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 username. Example : no-reply@example.com
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 : no-reply@example.comUsually 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
Database Configuration PostgreSQL database configuration (optional). PostgreSQL connection string. Example : postgresql://user:password@host:port/databaseManaged Configuration Managed deployment configuration for connecting self-hosted instances to managed services. Unique identifier for the managed deployment. Generated from the installer or the Pangolin dashboard . Example : he4g78wevj25msfSecret key for authenticating with the managed service. Generated from the installer or the Pangolin dashboard . Example : n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7dKeep this secret secure and do not share it publicly.
The managed service endpoint to connect to. This can only change with enterprise deployments. Example : https://pangolin.fossorial.ioDefault : https://pangolin.fossorial.io
Custom redirect endpoint for authentication flows. This can only change for enterprise deployments. Example : https://my-pangolin.example.comIf not specified, the default dashboard URL will be used.
Environment Variables Some configuration values can be set using environment variables for enhanced security:
Server Secret Variable : SERVER_SECRETConfig : server.secretUse this to avoid hardcoding secrets in your config file.
Email Password Variable : EMAIL_SMTP_PASSConfig : email.smtp_passKeep SMTP passwords secure using environment variables.
