Attempt to undo what github thinks I did when it was only a 5 line update.

This commit is contained in:
AstralDestiny
2026-02-12 23:56:37 -05:00
committed by Owen Schwartz
parent a32dec8a91
commit d22b90928b
2 changed files with 169 additions and 141 deletions

5
.vscode/settings.json vendored Normal file
View File

@@ -0,0 +1,5 @@
{
"githubPullRequests.ignoredPullRequestBranches": [
"main"
]
}

View File

@@ -3,6 +3,12 @@ title: "Wildcard Domains"
description: "Configure wildcard SSL certificates for automatic subdomain security with DNS-01 challenge" description: "Configure wildcard SSL certificates for automatic subdomain security with DNS-01 challenge"
--- ---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
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. 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.
<Warning> <Warning>
@@ -22,13 +28,15 @@ If you used the default settings during installation, your Traefik instance shou
## Benefits of Wildcard Certificates ## Benefits of Wildcard Certificates
<CardGroup cols={3}> <CardGroup cols={3}>
<Card icon="certificate" title="Single Certificate"> <Card title="Single Certificate" icon="certificate">
Secure unlimited subdomains with one certificate, reducing management overhead. Secure unlimited subdomains with one certificate, reducing management overhead.
</Card> </Card>
<Card icon="bolt" title="Instant Subdomains">
<Card title="Instant Subdomains" icon="bolt">
Add new subdomains without waiting for certificate generation (up to a few minutes). Add new subdomains without waiting for certificate generation (up to a few minutes).
</Card> </Card>
<Card icon="shield" title="Rate Limit Friendly">
<Card title="Rate Limit Friendly" icon="shield">
Reduce Let's Encrypt rate limit impact by using fewer certificate requests. Reduce Let's Encrypt rate limit impact by using fewer certificate requests.
</Card> </Card>
</CardGroup> </CardGroup>
@@ -53,11 +61,20 @@ If you used the default settings during installation, your Traefik instance shou
<Step title="Stop the stack"> <Step title="Stop the stack">
Make sure the stack is not running before making configuration changes. Make sure the stack is not running before making configuration changes.
</Step> </Step>
<Step title="Update Traefik configuration"> <Step title="Update Traefik configuration">
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. 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.
</Step> </Step>
<Step title="Configure Pangolin"> <Step title="Configure Pangolin">
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. 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
```
</Step> </Step>
</Steps> </Steps>
@@ -77,7 +94,7 @@ This is the default config generated by the installer. This is shown here for re
<Accordion title="1. HTTP Challenge Configuration"> <Accordion title="1. HTTP Challenge Configuration">
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} ```yaml title="traefik_config.yml" highlight={4,5}
certificatesResolvers: certificatesResolvers:
letsencrypt: letsencrypt:
acme: acme:
@@ -88,10 +105,11 @@ This is the default config generated by the installer. This is shown here for re
caServer: "https://acme-v02.api.letsencrypt.org/directory" caServer: "https://acme-v02.api.letsencrypt.org/directory"
``` ```
</Accordion> </Accordion>
<Accordion title="2. Dynamic Configuration"> <Accordion title="2. Dynamic Configuration">
Set the cert resolver to `letsencrypt` and the entrypoint to `websecure` in the dynamic config. Set the cert resolver to `letsencrypt` and the entrypoint to `websecure` in the dynamic config.
```yaml dynamic_config.yml ```yaml title="dynamic_config.yml"
next-router: next-router:
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)" rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
service: next-service service: next-service
@@ -109,7 +127,7 @@ This is the default config generated by the installer. This is shown here for re
<Step title="1. Configure DNS Challenge"> <Step title="1. Configure DNS 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} ```yaml title="traefik_config.yml" highlight={4,5}
certificatesResolvers: certificatesResolvers:
letsencrypt: letsencrypt:
acme: acme:
@@ -121,10 +139,11 @@ This is the default config generated by the installer. This is shown here for re
caServer: "https://acme-v02.api.letsencrypt.org/directory" caServer: "https://acme-v02.api.letsencrypt.org/directory"
``` ```
</Step> </Step>
<Step title="2. Add Wildcard Domains"> <Step title="2. Add Wildcard Domains">
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. 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 dynamic_config.yml {9,10,11,12} ```yaml title="dynamic_config.yml" highlight={8-12}
next-router: next-router:
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)" rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
service: next-service service: next-service
@@ -138,10 +157,11 @@ This is the default config generated by the installer. This is shown here for re
- "*.example.com" - "*.example.com"
``` ```
</Step> </Step>
<Step title="3. Add Environment Variables"> <Step title="3. Add Environment Variables">
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 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 docker-compose.yml {11,12,13} ```yaml title="docker-compose.yml" highlight={11-13}
traefik: traefik:
image: traefik:v3.4.0 image: traefik:v3.4.0
container_name: traefik container_name: traefik
@@ -182,18 +202,21 @@ This is the default config generated by the installer. This is shown here for re
<Step title="Start the stack"> <Step title="Start the stack">
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. 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.
</Step> </Step>
<Step title="Check logs"> <Step title="Check logs">
For debugging purposes, you may find it useful to set the log level of Traefik to `debug` in the `traefik_config.yml` file. For debugging purposes, you may find it useful to set the log level of Traefik to `debug` in the `traefik_config.yml` file.
</Step> </Step>
<Step title="Test new resource"> <Step title="Test new resource">
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. 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.
</Step> </Step>
<Step title="Verify certificate"> <Step title="Verify certificate">
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. 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.
</Step> </Step>
</Steps> </Steps>
```json {5} ```json highlight={5}
{ {
"Certificates": [ "Certificates": [
{ {
@@ -218,22 +241,22 @@ This is the default config generated by the installer. This is shown here for re
**Problem**: Wildcard certificate not being created. **Problem**: Wildcard certificate not being created.
**Solutions**: **Solutions**:
- Verify DNS provider credentials are correct - Verify DNS provider credentials are correct
- Check that API token has proper permissions - Check that API token has proper permissions
- Ensure domain ownership and DNS access - Ensure domain ownership and DNS access
- Review Traefik logs for specific error messages - Review Traefik logs for specific error messages
</Accordion> </Accordion>
<Accordion title="DNS challenge failing"> <Accordion title="DNS challenge failing">
**Problem**: DNS-01 challenge not completing. **Problem**: DNS-01 challenge not completing.
**Solutions**: **Solutions**:
- Verify DNS provider is supported by Traefik - Verify DNS provider is supported by Traefik
- Check API token permissions and scope - Check API token permissions and scope
- Ensure DNS propagation has completed - Ensure DNS propagation has completed
- Review provider-specific configuration - Review provider-specific configuration
</Accordion> </Accordion>
<Accordion title="Old certificates still being used"> <Accordion title="Old certificates still being used">
**Problem**: Traefik using old HTTP-01 certificates. **Problem**: Traefik using old HTTP-01 certificates.