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:
config.yml
Copy
# To see all available options, please visit the docs:
# https://docs.pangolin.net/
gerbil:
start_port: 51820
base_endpoint: "pangolin.example.com" # REPLACE WITH YOUR DOMAIN
# Optional network settings (defaults shown):
# subnet_group: "100.89.137.0/20"
# block_size: 24
# site_block_size: 30
app:
dashboard_url: "https://pangolin.example.com" # REPLACE WITH YOUR DOMAIN
log_level: "info"
telemetry:
anonymous_usage: true
domains:
domain1:
base_domain: "example.com" # REPLACE WITH YOUR DOMAIN
cert_resolver: "letsencrypt"
server:
secret: "your-strong-secret" # REPLACE
cors:
origins: ["https://pangolin.example.com"] # REPLACE WITH YOUR DOMAIN
methods: ["GET", "POST", "PUT", "DELETE", "PATCH"]
allowed_headers: ["X-CSRF-Token", "Content-Type"]
credentials: false
# Optional organization network settings (defaults shown):
# orgs:
# block_size: 24
# subnet_group: "100.90.128.0/20"
# utility_subnet_group: "100.96.128.0/20"
flags:
require_email_verification: false
disable_signup_without_invite: true
disable_user_create_org: false
allow_raw_resources: true
Generate a strong secret for
server.secret. Use at least 32 characters with a mix of letters, numbers, and special characters.If you need to CHANGE the server secret after the server has been started you must use the pangctl rotate-server-secret command to re-encrypt sensitive data. Follow docs here.Reference
This section contains the complete reference for all configuration options inconfig.yml.
Application Settings
Core application configuration including dashboard URL, logging, and general settings.
Show App
Show App
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: infoWhether 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:
falseTelemetry configuration settings.
Show Telemetry
Show Telemetry
Whether to enable anonymous usage telemetry.Default:
trueServer Configuration
Server ports, networking, and authentication settings.
Show Server
Show Server
The port for the front-end API that handles external requests.Example:
3000The port for the internal private-facing API.Example:
3001The port for the frontend server (Next.js).Example:
3002The port for the integration API (optional).Example:
3003The 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_tokenQuery parameter name for passing access tokens in requests.Example:
p_tokenDefault: p_tokenQuery parameter for session request tokens.Example:
p_session_requestDefault: p_session_requestCross-Origin Resource Sharing (CORS) configuration.
Show CORS
Show CORS
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:
trueNumber of proxy headers to trust for client IP detection.Example:
1Default: 1Use
1 if running behind a single reverse proxy like Traefik.Dashboard session duration in hours.Example:
720 (30 days)Default: 720Resource session duration in hours.Example:
720 (30 days)Default: 720Secret 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.If you need to CHANGE the server secret after the server has been started you must use the
pangctl rotate-server-secret command to re-encrypt sensitive data. Follow docs here.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.
Show Domains
Show Domains
Domain configuration with a unique key of your choice.
Show Domain Settings
Show Domain Settings
The base domain for this configuration.Example:
example.comThe 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.
Show Traefik
Show Traefik
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/certificatesInterval in milliseconds for monitoring configuration changes.Example:
5000Default: 5000Path to the dynamic certificate configuration file. This is used only with managed Pangolin deployments.Example:
/var/dynamic/cert_config.ymlDefault: /var/dynamic/cert_config.ymlPath to the dynamic router configuration file.Example:
/var/dynamic/router_config.ymlDefault: /var/dynamic/router_config.ymlSupported 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-vGerbil Tunnel Controller
Gerbil tunnel controller settings for WireGuard tunneling.
Show Gerbil
Show Gerbil
Domain name included in WireGuard configuration for tunnel connections.Example:
pangolin.example.comStarting port for WireGuard tunnels.Example:
51820Starting port for client WireGuard relay and hole punch port.Example:
21820Whether 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.Default:
100.89.137.0/20The default uses the CGNAT range to avoid conflicts with typical private networks.
Block size for Gerbil exit node CIDR ranges.Default:
24A /24 block provides 256 IP addresses for the Gerbil network.
Block size for site CIDR ranges connected to Gerbil.Default:
30A /30 block provides 4 IP addresses per site. Consider using /29 (8 IPs) or /28 (16 IPs) for sites with heavy WireGuard usage.
Organization Settings
Organization network configuration settings.
Show Organizations
Show Organizations
Block size for organization CIDR ranges.Default:
24A /24 block provides 256 IP addresses per organization. Determines the subnet size allocated to each organization for network isolation.
IP address CIDR range for organization subnets.Default:
100.90.128.0/20Example: 100.90.128.0/20Base subnet from which organization-specific subnets are allocated. Uses CGNAT range by default.
IP address CIDR range for utility subnets used by organizations.Default:
100.96.128.0/20Separate subnet range for utility network functions within organizations.
Rate Limiting
Rate limiting configuration for API requests.
Show Rate Limits
Show Rate Limits
Rate limit settings specifically for authentication endpoints.
Email Configuration
SMTP settings for sending transactional emails.
Show Email
Show Email
SMTP server hostname.Example:
smtp.gmail.comSMTP server port.Example:
587 (TLS) or 465 (SSL)SMTP username.Example:
no-reply@example.comSMTP password.Environment Variable:
EMAIL_SMTP_PASSWhether 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.Whether to fail on invalid server certificates.Default:
trueFeature Flags
Feature flags to control application behavior.
Show Flags
Show Flags
Whether to require email verification for new users.Default:
falseOnly enable this if you have email configuration set up.
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:
falseWhether to disable local site creation and management.Default:
falseWhen enabled, users cannot create sites that connect to local networks.
Whether to disable basic WireGuard site functionality.Default:
falseWhen enabled, only advanced WireGuard configurations are allowed.
Whether to disable product help banners in the UI at the top of screens.Default:
falseWhether to disable domains managed through the configuration file.Default:
falseWhen enabled, only domains created through the UI are allowed.
Whether to disable features that are only available in the Enterprise Edition from showing in the UI.Default:
falseWhen enabled, Enterprise-only features are hidden from the UI.
Database Configuration
PostgreSQL database configuration (optional).
Show PostgreSQL
Show PostgreSQL
PostgreSQL connection string.Example:
postgresql://user:password@host:port/databaseSee PostgreSQL documentation for setup instructions.
Read-only replica database configurations for load balancing.
Show Replica Configuration
Show Replica Configuration
Connection string for the read replica database.Example:
postgresql://user:password@replica-host:port/databaseDatabase connection pool settings.
Show Pool Settings
Show Pool Settings
Maximum number of connections to the primary database.Default:
20Example: 50Maximum number of connections to replica databases.Default:
10Example: 25Time in milliseconds before idle connections are closed.Default:
30000 (30 seconds)Example: 60000Time in milliseconds to wait for a database connection.Default:
5000 (5 seconds)Example: 10000Environment Variables
Some configuration values can be set using environment variables for enhanced security:| Name | Variable | Config |
|---|---|---|
| Server Secret | SERVER_SECRET | server.secret |
| Email Password | EMAIL_SMTP_PASS | email.smtp_pass |
| PostgreSQL Connection String | POSTGRES_CONNECTION_STRING | postgres.connection_string |