diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..a490b61
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,5 @@
+{
+ "githubPullRequests.ignoredPullRequestBranches": [
+ "main"
+ ]
+}
\ No newline at end of file
diff --git a/self-host/advanced/wild-card-domains.mdx b/self-host/advanced/wild-card-domains.mdx
index 9d347bb..5a5b3b4 100644
--- a/self-host/advanced/wild-card-domains.mdx
+++ b/self-host/advanced/wild-card-domains.mdx
@@ -3,34 +3,42 @@ title: "Wildcard Domains"
description: "Configure wildcard SSL certificates for automatic subdomain security with DNS-01 challenge"
---
+import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
+
+
+
+
+
Wildcard certificates allow you to secure unlimited subdomains with a single SSL certificate, eliminating the need to generate individual certificates for each subdomain. Pangolin uses Traefik's built-in Let's Encrypt integration to automatically manage these certificates.
- Before setting up wildcard certificates, you must have a domain that you own and control. You must also have access to the DNS records for this domain.
+Before setting up wildcard certificates, you must have a domain that you own and control. You must also have access to the DNS records for this domain.
- Since Pangolin uses Traefik as a reverse proxy, it has built-in support for Let's Encrypt certificates. This allows you to easily secure your Pangolin instance and all proxied resources with HTTPS. Let's Encrypt provides free SSL certificates, which are automatically renewed.
+Since Pangolin uses Traefik as a reverse proxy, it has built-in support for Let's Encrypt certificates. This allows you to easily secure your Pangolin instance and all proxied resources with HTTPS. Let's Encrypt provides free SSL certificates, which are automatically renewed.
If you used the default settings during installation, your Traefik instance should be set up to use `HTTP-01` challenge for certificate generation. This challenge is the easiest to configure and requires that the Traefik instance be accessible from the internet on port 80.
- It is highly recommended that you read the [official Traefik documentation](https://doc.traefik.io/traefik/https/acme/) on ACME and Let's Encrypt before proceeding.
+It is highly recommended that you read the [official Traefik documentation](https://doc.traefik.io/traefik/https/acme/) on ACME and Let's Encrypt before proceeding.
## Benefits of Wildcard Certificates
-
- Secure unlimited subdomains with one certificate, reducing management overhead.
-
-
- Add new subdomains without waiting for certificate generation (up to a few minutes).
-
-
- Reduce Let's Encrypt rate limit impact by using fewer certificate requests.
-
+
+ Secure unlimited subdomains with one certificate, reducing management overhead.
+
+
+
+ Add new subdomains without waiting for certificate generation (up to a few minutes).
+
+
+
+ Reduce Let's Encrypt rate limit impact by using fewer certificate requests.
+
### Examples
@@ -44,27 +52,36 @@ If you used the default settings during installation, your Traefik instance shou
- `blog.subdomain.example.com`
- The [rate limits](https://letsencrypt.org/docs/rate-limits/) for Let's Encrypt are per domain. Using a wildcard certificate reduces the number of domains you have, which can help you avoid hitting these limits.
+The [rate limits](https://letsencrypt.org/docs/rate-limits/) for Let's Encrypt are per domain. Using a wildcard certificate reduces the number of domains you have, which can help you avoid hitting these limits.
## Setting Up Wildcard Certificates
-
- Make sure the stack is not running before making configuration changes.
-
-
- Update the Traefik configuration to use the DNS-01 challenge instead of the HTTP-01 challenge. This tells Traefik to use your DNS provider to create the DNS records needed for the challenge.
-
-
- Set the `prefer_wildcard_cert` flag to `true` in the Pangolin configuration file for your domain. Or update it on the Domains page in the Pangolin dashboard.
-
+
+ Make sure the stack is not running before making configuration changes.
+
+
+
+ Update the Traefik configuration to use the DNS-01 challenge instead of the HTTP-01 challenge. This tells Traefik to use your DNS provider to create the DNS records needed for the challenge.
+
+
+
+ Set the `prefer_wildcard_cert` flag to `true` in the Pangolin configuration file for your domain. This is also configurable in the Pangolin dashboard (once restarted).
+
+```yaml title="config.yml" highlight={4}
+ domains:
+ domain1:
+ base_domain: "example.com"
+ prefer_wildcard_cert: true
+ ```
+
- This setting will try to encourage Traefik to request one wildcard certificate for each level of the domain used by your existing resources.
+This setting will try to encourage Traefik to request one wildcard certificate for each level of the domain used by your existing resources.
- **Example**: If you have two resources `blog.example.com` and `blog.subdomain.example.com`, Traefik should try to request a wildcard certificate for `*.example.com` and `*.subdomain.example.com` automatically for you.
+**Example**: If you have two resources `blog.example.com` and `blog.subdomain.example.com`, Traefik should try to request a wildcard certificate for `*.example.com` and `*.subdomain.example.com` automatically for you.
## Traefik Configuration
@@ -74,126 +91,132 @@ If you used the default settings during installation, your Traefik instance shou
This is the default config generated by the installer. This is shown here for reference to compare with the wildcard config below.
-
- Tell Traefik to use the `web` entrypoint for the HTTP challenge.
+
+ Tell Traefik to use the `web` entrypoint for the HTTP challenge.
- ```yaml traefik_config.yml {4,5}
- certificatesResolvers:
- letsencrypt:
- acme:
- httpChallenge:
- entryPoint: web
- email: admin@example.com
- storage: "/letsencrypt/acme.json"
- caServer: "https://acme-v02.api.letsencrypt.org/directory"
- ```
-
-
- Set the cert resolver to `letsencrypt` and the entrypoint to `websecure` in the dynamic config.
+ ```yaml title="traefik_config.yml" highlight={4,5}
+ certificatesResolvers:
+ letsencrypt:
+ acme:
+ httpChallenge:
+ entryPoint: web
+ email: admin@example.com
+ storage: "/letsencrypt/acme.json"
+ caServer: "https://acme-v02.api.letsencrypt.org/directory"
+ ```
+
- ```yaml dynamic_config.yml
- next-router:
- rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
- service: next-service
- entryPoints:
- - websecure
- tls:
- certResolver: letsencrypt
- ```
-
+
+ Set the cert resolver to `letsencrypt` and the entrypoint to `websecure` in the dynamic config.
+
+ ```yaml title="dynamic_config.yml"
+ next-router:
+ rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
+ service: next-service
+ entryPoints:
+ - websecure
+ tls:
+ certResolver: letsencrypt
+ ```
+
### Wildcard Config for DNS-01 Challenge
-
- Tell Traefik to use your DNS provider for the DNS challenge. In this example, we are using Cloudflare.
+
+ Tell Traefik to use your DNS provider for the DNS challenge. In this example, we are using Cloudflare.
- ```yaml traefik_config.yml {4,5}
- certificatesResolvers:
- letsencrypt:
- acme:
- dnsChallenge:
- provider: "cloudflare" # your DNS provider
- # 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"
- ```
-
-
- Add the domain and wildcard domain to the domains section of the next (front end) router in the dynamic config. This tells Traefik to generate a wildcard certificate for the base domain and all subdomains.
+ ```yaml title="traefik_config.yml" highlight={4,5}
+ certificatesResolvers:
+ letsencrypt:
+ acme:
+ dnsChallenge:
+ provider: "cloudflare" # your DNS provider
+ # 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"
+ ```
+
- ```yaml dynamic_config.yml {9,10,11,12}
- 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"
- ```
-
-
- Add the environment variables for your DNS provider to the Traefik service in the docker compose file. This allows Traefik to authenticate with your DNS provider to create the DNS records needed for the challenge.
+
+ Add the domain and wildcard domain to the domains section of the next (front end) router in the dynamic config. This tells Traefik to generate a wildcard certificate for the base domain and all subdomains.
- ```yaml docker-compose.yml {11,12,13}
- traefik:
- image: traefik:v3.4.0
- container_name: traefik
- restart: unless-stopped
- network_mode: service:gerbil
- depends_on:
- pangolin:
- condition: service_healthy
- command:
- - --configFile=/etc/traefik/traefik_config.yml
- # Add the environment variables for your DNS provider.
- environment:
- CLOUDFLARE_DNS_API_TOKEN: "your-cloudflare-api-token"
- volumes:
- - ./config/traefik:/etc/traefik:ro
- - ./config/letsencrypt:/letsencrypt
- ```
-
+ ```yaml title="dynamic_config.yml" highlight={8-12}
+ 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"
+ ```
+
+
+
+ Add the environment variables for your DNS provider to the Traefik service in the docker compose file. This allows Traefik to authenticate with your DNS provider to create the DNS records needed for the challenge.
+
+ ```yaml title="docker-compose.yml" highlight={11-13}
+ traefik:
+ image: traefik:v3.4.0
+ container_name: traefik
+ restart: unless-stopped
+ network_mode: service:gerbil
+ depends_on:
+ pangolin:
+ condition: service_healthy
+ command:
+ - --configFile=/etc/traefik/traefik_config.yml
+ # Add the environment variables for your DNS provider.
+ environment:
+ CLOUDFLARE_DNS_API_TOKEN: "your-cloudflare-api-token"
+ volumes:
+ - ./config/traefik:/etc/traefik:ro
+ - ./config/letsencrypt:/letsencrypt
+ ```
+
- If you're using Cloudflare, make sure your API token has the permissions Zone/Zone/Read and Zone/DNS/Edit and make sure it applies to all zones.
+If you're using Cloudflare, make sure your API token has the permissions Zone/Zone/Read and Zone/DNS/Edit and make sure it applies to all zones.
- Traefik supports most DNS providers. You can find a full list of supported providers and how to configure them in the [Traefik documentation on providers](https://doc.traefik.io/traefik/https/acme/#providers).
+Traefik supports most DNS providers. You can find a full list of supported providers and how to configure them in the [Traefik documentation on providers](https://doc.traefik.io/traefik/https/acme/#providers).
## Verify it Works
-
- You can ensure Traefik doesn't try to use the old certs by deleting the previously used `acme.json` file. This will force Traefik to generate a new certificate on the next start.
-
+
+ You can ensure Traefik doesn't try to use the old certs by deleting the previously used `acme.json` file. This will force Traefik to generate a new certificate on the next start.
+
-
- Start the stack and watch the logs. You should notice that Traefik is making calls to your DNS provider to create the necessary records to complete the challenge.
-
-
- For debugging purposes, you may find it useful to set the log level of Traefik to `debug` in the `traefik_config.yml` file.
-
-
- After Traefik is done waiting for the cert to verify, try to create a new resource with an unused subdomain. Traefik should not try to generate a new certificate, but instead use the wildcard certificate. The domain should also be secured immediately instead of waiting for a new certificate to be generated.
-
-
- You can also check the volume (in the example above at `config/letsencrypt/`) for the correct certificates. In the `acme.json` file you should see something similar to the following. Note the `*.` in the domain.
-
+
+ Start the stack and watch the logs. You should notice that Traefik is making calls to your DNS provider to create the necessary records to complete the challenge.
+
+
+
+ For debugging purposes, you may find it useful to set the log level of Traefik to `debug` in the `traefik_config.yml` file.
+
+
+
+ After Traefik is done waiting for the cert to verify, try to create a new resource with an unused subdomain. Traefik should not try to generate a new certificate, but instead use the wildcard certificate. The domain should also be secured immediately instead of waiting for a new certificate to be generated.
+
+
+
+ You can also check the volume (in the example above at `config/letsencrypt/`) for the correct certificates. In the `acme.json` file you should see something similar to the following. Note the `*.` in the domain.
+
-```json {5}
+```json highlight={5}
{
"Certificates": [
{
@@ -214,29 +237,29 @@ This is the default config generated by the installer. This is shown here for re
## Troubleshooting
-
- **Problem**: Wildcard certificate not being created.
+
+ **Problem**: Wildcard certificate not being created.
+
+ **Solutions**:
+ - Verify DNS provider credentials are correct
+ - Check that API token has proper permissions
+ - Ensure domain ownership and DNS access
+ - Review Traefik logs for specific error messages
+
- **Solutions**:
+
+ **Problem**: DNS-01 challenge not completing.
+
+ **Solutions**:
+ - Verify DNS provider is supported by Traefik
+ - Check API token permissions and scope
+ - Ensure DNS propagation has completed
+ - Review provider-specific configuration
+
- - Verify DNS provider credentials are correct
- - Check that API token has proper permissions
- - Ensure domain ownership and DNS access
- - Review Traefik logs for specific error messages
-
-
- **Problem**: DNS-01 challenge not completing.
-
- **Solutions**:
-
- - Verify DNS provider is supported by Traefik
- - Check API token permissions and scope
- - Ensure DNS propagation has completed
- - Review provider-specific configuration
-
-
- **Problem**: Traefik using old HTTP-01 certificates.
-
- **Solution**: Delete the `acme.json` file to force new certificate generation.
-
+
+ **Problem**: Traefik using old HTTP-01 certificates.
+
+ **Solution**: Delete the `acme.json` file to force new certificate generation.
+
\ No newline at end of file