Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt

Use this file to discover all available pages before exploring further.

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
Wildcard certificates let one certificate cover every first-level subdomain of a domain, such as *.example.com. They are useful when you create many resources under the same base domain because Traefik does not need to request a new certificate for every resource hostname. Traefik is the reverse proxy in the self-hosted Pangolin stack. It receives HTTPS traffic, requests certificates from Let’s Encrypt, and routes requests to Pangolin resources. A Traefik certificate resolver is the named block of Traefik configuration that tells Traefik how to request certificates.
Wildcard certificates require a DNS-01 challenge. You must control the domain’s DNS records and have API credentials for a DNS provider supported by Traefik.
Let’s Encrypt only issues wildcard certificates through DNS-01 challenges. See the Traefik ACME documentation and Lego DNS provider list for provider-specific options.

​
How Wildcards Work

  • *.example.com covers app.example.com, api.example.com, and blog.example.com.
  • *.example.com does not cover app.internal.example.com; that needs *.internal.example.com.
  • A wildcard certificate can reduce Let’s Encrypt rate limit pressure because many resource hostnames can reuse the same certificate.
Pangolin can prefer wildcard certificates when it generates Traefik router configuration. For example, if you have resources at blog.example.com and api.example.com, Pangolin can ask Traefik to request *.example.com instead of separate certificates for each hostname.

​
Benefits

Single Certificate

Secure many subdomains under the same base domain with one certificate.

Instant Subdomains

New resource subdomains can use the existing wildcard certificate instead of waiting for a new certificate request.

Rate Limit Friendly

Fewer certificate requests can help reduce the chance of hitting Let’s Encrypt rate limits.

​
Choose a Resolver Strategy

Most installs start with one Traefik certificate resolver named letsencrypt that uses HTTP-01:
traefik_config.yml
certificatesResolvers:
  letsencrypt:
    acme:
      httpChallenge:
        entryPoint: web
      email: "admin@example.com"
      storage: "/letsencrypt/acme.json"
      caServer: "https://acme-v02.api.letsencrypt.org/directory"
HTTP-01 proves domain ownership by serving a challenge over port 80. DNS-01 proves domain ownership by creating a temporary DNS record through your DNS provider. Wildcard certificates require DNS-01. For wildcard certificates, you have two good options. Most users should replace the existing letsencrypt resolver with DNS-01; add a second resolver only if you know you need both HTTP-01 and DNS-01.
StrategyWhen to use it
Replace letsencrypt with DNS-01Simplest option. Use this if all certificates can be issued through your DNS provider.
Add a second resolverUse this if you want to keep HTTP-01 for some routers and use DNS-01 only for wildcard domains.
Traefik does not automatically apply a resolver just because it exists. Each router must reference the resolver with tls.certResolver, and Pangolin’s cert_resolver setting must match the Traefik resolver name.
In the Pangolin dashboard, default uses Pangolin’s configured traefik.cert_resolver value. In a standard install, that default value is letsencrypt.

​
Configure DNS-01 Wildcards

1

Stop the stack

Stop Pangolin before editing Traefik and Pangolin configuration.
sudo docker compose down
2

Update the Traefik resolver

Replace the default HTTP-01 resolver with a DNS-01 resolver. This example uses Cloudflare.
config/traefik/traefik_config.yml
certificatesResolvers:
  letsencrypt:
    acme:
      dnsChallenge:
        provider: "cloudflare"
        # See https://doc.traefik.io/traefik/https/acme/#providers
      email: "admin@example.com"
      storage: "/letsencrypt/acme.json"
      caServer: "https://acme-v02.api.letsencrypt.org/directory"
The resolver name is the key under certificatesResolvers. In this example it is letsencrypt, so Pangolin’s cert_resolver and any Traefik tls.certResolver values must also use letsencrypt.
3

Add DNS provider credentials

Add the environment variables required by your DNS provider to the traefik service. Cloudflare requires an API token with Zone:Read and DNS:Edit permissions for every zone Traefik needs to solve challenges for.
docker-compose.yml
traefik:
  image: docker.io/traefik:v3.6
  container_name: traefik
  restart: unless-stopped
  network_mode: service:gerbil
  depends_on:
    pangolin:
      condition: service_healthy
  command:
    - --configFile=/etc/traefik/traefik_config.yml
  environment:
    CLOUDFLARE_DNS_API_TOKEN: "your-cloudflare-api-token" # REPLACE
  volumes:
    - ./config/traefik:/etc/traefik:ro
    - ./config/letsencrypt:/letsencrypt
4

Tell Pangolin to prefer wildcard certificates

Set prefer_wildcard_cert: true for the domain in config/config.yml.
config/config.yml
domains:
  domain1:
    base_domain: "example.com"
    prefer_wildcard_cert: true
    cert_resolver: "letsencrypt"
If you manage domains through the Pangolin dashboard instead, restart Pangolin and enable wildcard preference on the domain there. The dashboard also lets you set the domain’s certificate resolver; it must match the resolver name in Traefik.
5

Restart the stack

Start the stack and watch Traefik logs. You should see Traefik create DNS challenge records through your provider.
sudo docker compose up -d
sudo docker compose logs -f traefik

​
Multiple Certificate Resolvers

You can define more than one Traefik certificate resolver. This is useful when you want to keep HTTP-01 available as the default resolver, but use a DNS-01 resolver for wildcard domains.
config/traefik/traefik_config.yml
certificatesResolvers:
  letsencrypt:
    acme:
      httpChallenge:
        entryPoint: web
      email: "admin@example.com"
      storage: "/letsencrypt/acme-http.json"
      caServer: "https://acme-v02.api.letsencrypt.org/directory"

  letsencrypt-dns:
    acme:
      dnsChallenge:
        provider: "cloudflare"
      email: "admin@example.com"
      storage: "/letsencrypt/acme-dns.json"
      caServer: "https://acme-v02.api.letsencrypt.org/directory"
Then point the wildcard domain at the DNS resolver. You can do this in config/config.yml for file-managed domains:
config/config.yml
domains:
  domain1:
    base_domain: "example.com"
    prefer_wildcard_cert: true
    cert_resolver: "letsencrypt-dns"
If you want UI-created domains to use the DNS resolver by default, set the Traefik defaults too:
config/config.yml
traefik:
  cert_resolver: "letsencrypt-dns"
  prefer_wildcard_cert: true
For dashboard-managed domains, open the domain settings in Pangolin and set the certificate resolver to the custom Traefik resolver name, such as letsencrypt-dns. Enable wildcard preference on the same domain if you want Pangolin to request wildcard certificates for resources under that domain.
If you split ACME storage across multiple files, configure Pangolin’s private acme.acme_json_path setting as the directory that contains them, for example config/letsencrypt. Pangolin will scan the directory for ACME JSON files, including nested files. See ACME configuration.

​
Dashboard Certificate

The prefer_wildcard_cert setting affects resource routers generated by Pangolin. If you also want Traefik to request a wildcard certificate for the Pangolin dashboard router, add the wildcard domain to the dashboard router’s tls.domains list in config/traefik/dynamic_config.yml.
config/traefik/dynamic_config.yml
next-router:
  rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
  service: next-service
  entryPoints:
    - websecure
  tls:
    certResolver: letsencrypt
    domains:
      - main: "example.com"
        sans:
          - "*.example.com"
If you use a second resolver, set certResolver to that resolver name, such as letsencrypt-dns.

​
Verify It Works

If Traefik already issued certificates with the old resolver, clear the old certificates before testing so Traefik requests them again. Remove the relevant ACME storage file, or use pangctl clear-certs if Pangolin has already synced stale certificates.
1

Create or open a resource

Create a resource on an unused subdomain such as test.example.com, or open an existing resource under the same base domain.
2

Check Traefik logs

Traefik should use the DNS-01 resolver and should not need a separate certificate for every resource hostname after the wildcard certificate exists.
sudo docker compose logs traefik
3

Inspect ACME storage

Check the ACME storage file in config/letsencrypt. The certificate domain should include a wildcard SAN such as *.example.com.
{
  "Certificates": [
    {
      "domain": {
        "main": "example.com",
        "sans": ["*.example.com"]
      },
      "certificate": "...",
      "key": "...",
      "Store": "default"
    }
  ]
}

​
Troubleshooting

Confirm the DNS provider is correct, the provider environment variables are present on the traefik service, and the API token has permission to edit DNS records for the zone.
Check the resolver name. The router’s tls.certResolver and Pangolin’s cert_resolver must match the DNS-01 resolver name exactly.
Clear old certificates so Traefik can request them again. You can remove the relevant ACME storage file, or use pangctl clear-certs if Pangolin has already synced stale certificates.
Review Traefik debug logs, confirm DNS propagation is working, and check whether your DNS provider requires additional propagation delay or custom resolvers. If your DNS provider has a firewall, make sure it allows DNS traffic, typically UDP on port 53.