Configuration File

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:

config.yml

app:
  dashboard_url: "http://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

app

object

required

Core application configuration including dashboard URL, logging, and general settings.

Show App

dashboard_url

string

required

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.

log_level

string

The logging level for the application.Options: debug, info, warn, errorDefault: info

save_logs

boolean

Whether to save logs to files in the config/logs/ directory.Default: false

When enabled, logs rotate automatically:

Max file size: 20MB
Max files: 7 days

log_failed_attempts

boolean

Whether to log failed authentication attempts for security monitoring.Default: false

Server Configuration

server

object

required

Server ports, networking, and authentication settings.

Show Server

external_port

integer

The port for the front-end API that handles external requests.Example: 3000

internal_port

integer

The port for the internal private-facing API.Example: 3001

next_port

integer

The port for the frontend server (Next.js).Example: 3002

integration_port

integer

The port for the integration API (optional).Example: 3003

internal_hostname

string

The hostname of the Pangolin container for internal communication.Example: pangolin

If 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

string

Query parameter name for passing access tokens in requests.Example: p_tokenDefault: p_token

resource_access_token_headers

object

HTTP headers for passing access tokens in requests.

Show Headers

string

Header name for access token ID.Example: P-Access-Token-Id

token

string

Header name for access token.Example: P-Access-Token

resource_session_request_param

string

Query parameter for session request tokens.Example: p_session_requestDefault: p_session_request

cors

object

Cross-Origin Resource Sharing (CORS) configuration.

Show CORS

origins

array of strings

Allowed origins for cross-origin requests.Example: ["https://pangolin.example.com"]

methods

array of strings

Allowed HTTP methods for CORS requests.Example: ["GET", "POST", "PUT", "DELETE", "PATCH"]

allowed_headers

array of strings

Allowed HTTP headers in CORS requests.Example: ["X-CSRF-Token", "Content-Type"]

credentials

boolean

Whether to allow credentials in CORS requests.Default: true

trust_proxy

integer

Number of proxy headers to trust for client IP detection.Example: 1Default: 1

Use 1 if running behind a single reverse proxy like Traefik.

dashboard_session_length_hours

integer

Dashboard session duration in hours.Example: 720 (30 days)Default: 720

resource_session_length_hours

integer

Resource session duration in hours.Example: 720 (30 days)Default: 720

secret

string

required

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

domains

object

required

Domain settings for SSL certificates and routing.At least one domain must be configured.

Show Domains

<domain_key>

object

Domain configuration with a unique key of your choice.

Show Domain Settings

base_domain

string

required

The base domain for this configuration.Example: example.com

cert_resolver

string

required

The Traefik certificate resolver name.Example: letsencrypt

This must match the certificate resolver name in your Traefik configuration.

prefer_wildcard_cert

boolean

Whether to prefer wildcard certificates for this domain.Example: true

Useful for domains with many subdomains to reduce certificate management overhead.

Traefik Integration

traefik

object

Traefik reverse proxy configuration settings.

Show Traefik

http_entrypoint

string

The Traefik entrypoint name for HTTP traffic.Example: web

Must match the entrypoint name in your Traefik configuration.

https_entrypoint

string

The Traefik entrypoint name for HTTPS traffic.Example: websecure

Must match the entrypoint name in your Traefik configuration.

cert_resolver

string

The default certificate resolver for domains created through the UI.Example: letsencrypt

This only applies to domains created through the Pangolin dashboard.

prefer_wildcard_cert

boolean

Whether to prefer wildcard certificates for UI-created domains.Example: true

This only applies to domains created through the Pangolin dashboard.

additional_middlewares

array of strings

Additional Traefik middlewares to apply to resource routers.Example: ["middleware1", "middleware2"]

These middlewares must be defined in your Traefik dynamic configuration.

Gerbil Tunnel Controller

gerbil

object

required

Gerbil tunnel controller settings for WireGuard tunneling.

Show Gerbil

base_endpoint

string

required

Domain name included in WireGuard configuration for tunnel connections.Example: pangolin.example.com

start_port

integer

Starting port for WireGuard tunnels.Example: 51820

use_subdomain

boolean

Whether to assign unique subdomains to Gerbil exit nodes.Default: false

Keep this set to false for most deployments.

subnet_group

string

IP address CIDR range for Gerbil exit node subnets.Example: 10.0.0.0/8

block_size

integer

Block size for Gerbil exit node CIDR ranges.Example: 24

site_block_size

integer

Block size for site CIDR ranges connected to Gerbil.Example: 26

Rate Limiting

rate_limits

object

Rate limiting configuration for API requests.

Show Rate Limits

global

object

Global rate limit settings for all external API requests.

Show Global

window_minutes

integer

Time window for rate limiting in minutes.Example: 1

max_requests

integer

Maximum number of requests allowed in the time window.Example: 100

Email Configuration

object

SMTP settings for sending transactional emails.

Show Email

smtp_host

string

SMTP server hostname.Example: smtp.gmail.com

smtp_port

integer

SMTP server port.Example: 587 (TLS) or 465 (SSL)

smtp_user

string

SMTP username.Example: no-reply@example.com

smtp_pass

string

SMTP password.Environment Variable: EMAIL_SMTP_PASS

smtp_secure

boolean

Whether to use secure connection (SSL/TLS).Default: false

Enable this when using port 465 (SSL).

no_reply

string

From address for sent emails.Example: no-reply@example.com

Usually the same as smtp_user.

smtp_tls_reject_unauthorized

boolean

Whether to fail on invalid server certificates.Default: true

Feature Flags

flags

object

Feature flags to control application behavior.

Show Flags

require_email_verification

boolean

Whether to require email verification for new users.Default: false

Only enable this if you have email configuration set up.

Whether to disable public user registration.Default: false

Users can still sign up with valid invites when enabled.

disable_user_create_org

boolean

Whether to prevent users from creating organizations.Default: false

Server admins can always create organizations.

allow_base_domain_resources

boolean

Whether to allow resources on base domains.Default: true

When disabled, only subdomain resources are allowed.

enable_integration_api

boolean

Whether to enable the integration API.Default: false

Database Configuration

postgres

object

PostgreSQL database configuration (optional).

Show PostgreSQL

connection_string

string

required

PostgreSQL connection string.Example: postgresql://user:password@host:port/database

See PostgreSQL documentation for setup instructions.

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.

About

Manage Pangolin

Self-host Pangolin

Development

Setting up your `config.yml`

Reference

Application Settings

Server Configuration

Domain Configuration

Traefik Integration

Gerbil Tunnel Controller

Rate Limiting

Email Configuration

Feature Flags

Database Configuration

Environment Variables

Server Secret

Email Password

About

Manage Pangolin

Self-host Pangolin

Development

​Setting up your config.yml

​Reference

​Application Settings

​Server Configuration

​Domain Configuration

​Traefik Integration

​Gerbil Tunnel Controller

​Rate Limiting

​Email Configuration

​Feature Flags

​Database Configuration

​Environment Variables

Server Secret

Email Password

Setting up your `config.yml`

Reference

Application Settings

Server Configuration

Domain Configuration

Traefik Integration

Gerbil Tunnel Controller

Rate Limiting

Email Configuration

Feature Flags

Database Configuration

Environment Variables