Skip to content

feat: add wildcard domain support with DNS challenge#3929

Open
semihanadolu wants to merge 6 commits intoDokploy:canaryfrom
semihanadolu:feat/wildcard-domain-support
Open

feat: add wildcard domain support with DNS challenge#3929
semihanadolu wants to merge 6 commits intoDokploy:canaryfrom
semihanadolu:feat/wildcard-domain-support

Conversation

@semihanadolu
Copy link

@semihanadolu semihanadolu commented Mar 7, 2026

What does this PR do?

Adds full wildcard domain support (e.g., *.example.com) to Dokploy, including correct Traefik routing rules, automatic DNS challenge certificate resolver selection, and user-friendly UI guidance.

Changes

Backend

  • Router rule fix: Wildcard domains now use HostRegexp() instead of Host() for Traefik v3 Go regex syntax
  • Auto DNS resolver: When a wildcard domain uses Let's Encrypt, the letsencrypt-dns cert resolver is automatically selected
  • Default Traefik config: Added letsencrypt-dns resolver with DNS challenge alongside the existing letsencrypt HTTP challenge resolver
  • Validation: Wildcard domain format validation (*.example.com) and blocks none certificate type for wildcard HTTPS domains

Frontend

  • Wildcard info alert: When user enters a *. host, an info message explains wildcard matching
  • DNS Challenge warning: When wildcard + Let's Encrypt is selected, a warning explains DNS challenge is required with a link to Traefik Environment settings
  • Auto-open Traefik Env dialog: Clicking the warning link navigates to Settings and automatically opens the Traefik Environment dialog with DNS provider setup guide
  • DNS provider guide: Shows common provider credentials (Cloudflare, Route53, DigitalOcean, Hetzner)
Screenshot 2026-03-08 at 1 14 54 AM

How to test

  1. Create/edit a domain with host *.example.com
  2. Verify the wildcard info alert appears
  3. Enable HTTPS → Select Let's Encrypt → Verify DNS challenge warning appears
  4. Click the "Settings → Web Server → Traefik Environment" link → Verify dialog auto-opens with DNS guide
  5. Try selecting certificate type "None" with wildcard + HTTPS → Verify validation error

Greptile Summary

This PR adds full wildcard domain support (*.example.com) to Dokploy, including correct Traefik v3 HostRegexp routing rules, automatic letsencrypt-dns cert resolver selection, a new default DNS challenge resolver in the Traefik config, and UI guidance for DNS provider setup.

Key concerns:

  • Silent failure for existing installations: createDefaultTraefikConfig returns early when traefik.yml already exists, so the new letsencrypt-dns resolver block is never written for any currently-running Dokploy instance. Users who upgrade and configure a wildcard domain will get a router referencing certresolver=letsencrypt-dns, but Traefik won't find the resolver — certificate issuance will silently fail.
  • Incomplete DNS guide for non-Cloudflare users: The Traefik Env dialog guide correctly lists API credential env vars (e.g., CF_DNS_API_TOKEN, AWS_ACCESS_KEY_ID), but omits the fact that TRAEFIK_DNS_PROVIDER must also be set in Dokploy's environment to match the chosen provider. Without it, the generated traefik.yml defaults to provider: cloudflare, causing Traefik to use Cloudflare API calls with the wrong credentials.
  • Dialog description always references wildcard SSL: The updated DialogDescription unconditionally mentions wildcard SSL even when the dialog is opened in non-wildcard settings contexts.

Confidence Score: 2/5

  • Not safe to merge — wildcard HTTPS will silently fail on all existing installations, and the DNS provider setup guide is incomplete for non-Cloudflare users.
  • The cert-resolver migration issue means that the primary use case (wildcard + Let's Encrypt on an existing install) will produce no certificates without manual intervention. Combined with the missing TRAEFIK_DNS_PROVIDER documentation, non-Cloudflare users following the in-app guide will also fail silently.
  • packages/server/src/setup/traefik-setup.ts (migration of existing configs) and apps/dokploy/components/dashboard/settings/web-server/edit-traefik-env.tsx (incomplete DNS provider guidance).

Comments Outside Diff (2)

  1. packages/server/src/setup/traefik-setup.ts, line 401-402 (link)

    acme.json is explicitly chmod'd to 600 (line 401), which Traefik requires. However, the new acme-dns.json referenced in the config is never initialized or chmod'd. For consistency and to prevent Traefik permission errors, add equivalent initialization:

    const acmeDnsJsonPath = path.join(DYNAMIC_TRAEFIK_PATH, "acme-dns.json");
    if (existsSync(acmeDnsJsonPath)) {
      chmodSync(acmeDnsJsonPath, "600");
    }
  2. packages/server/src/setup/traefik-setup.ts, line 395-423 (link)

    Existing installations won't receive the letsencrypt-dns resolver

    createDefaultTraefikConfig (which writes traefik.yml) returns early when the file already exists:

    } else if (stats.isFile()) {
      console.log("Main config already exists");
      return;  // <-- skips all changes for existing installs
    }

    This means any Dokploy instance that was set up before this PR will never have the letsencrypt-dns cert resolver written to its traefik.yml. When a wildcard domain is configured with letsencrypt, the router will reference certresolver=letsencrypt-dns but Traefik will silently ignore the resolver (or log an error) because it isn't defined in the config — certificates will never be issued.

    Existing users will need to either manually add the resolver block to their traefik.yml or delete the file and let Dokploy regenerate it. Consider adding a migration step or an explicit check that merges the new resolver into an existing config.

Last reviewed commit: 33cb7b7

Greptile also left 2 inline comments on this PR.

- Use HostRegexp for wildcard domains (*.example.com) in Traefik v3 syntax
- Auto-select letsencrypt-dns resolver for wildcard domains with HTTPS
- Add letsencrypt-dns certificate resolver with DNS challenge to default Traefik config
- Show wildcard domain info alert in domain form
- Show DNS challenge configuration warning when wildcard + Let's Encrypt is selected
- Guide users to configure DNS provider credentials in Traefik Environment settings
- Validate wildcard domain format (must be *.example.com)
- Block 'none' certificate type for wildcard domains with HTTPS
- Add DNS challenge provider guide in Traefik Environment dialog
- Show common DNS provider env vars (Cloudflare, Route53, DigitalOcean, Hetzner)
- Update placeholder with DNS challenge credential examples
- Handle ?traefikEnv=true in Web Server settings to automatically open Traefik Env dialog
- Show DNS challenge instructions only when dialog is opened via wildcard warning link
…g link

- Move URL parameter reading from EditTraefikEnv to WebServer component
- EditTraefikEnv was inside DropdownMenu and never mounted on page load
- Render standalone EditTraefikEnv at WebServer level with autoOpen prop
- DialogTrigger is now conditional (only rendered when children exist)
- Clean up URL parameter when dialog is closed
@dosubot dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. enhancement New feature or request labels Mar 7, 2026
@semihanadolu semihanadolu marked this pull request as draft March 8, 2026 09:05
- traefik-setup.ts: use TRAEFIK_DNS_PROVIDER env var with cloudflare fallback
- edit-traefik-env.tsx: fix useEffect to setIsOpen(autoOpen) pattern
- edit-traefik-env.tsx: context-aware placeholder (HTTP challenge for normal, DNS for wildcard)
@semihanadolu semihanadolu force-pushed the feat/wildcard-domain-support branch from aaf932b to 33cb7b7 Compare March 8, 2026 09:08
@semihanadolu semihanadolu marked this pull request as ready for review March 8, 2026 09:23
@dosubot dosubot bot added the bug Something isn't working label Mar 8, 2026
Comment on lines +135 to +147
{showDnsGuide && (
<AlertBlock type="info">
<strong>DNS Challenge for Wildcard Certificates:</strong>{" "}
To use wildcard domains (e.g., *.example.com) with HTTPS,
add your DNS provider API credentials here. Common providers:
<ul className="mt-1 ml-4 list-disc text-xs space-y-0.5">
<li><strong>Cloudflare:</strong> <code>CF_DNS_API_TOKEN=your_token</code></li>
<li><strong>Route53:</strong> <code>AWS_ACCESS_KEY_ID</code> + <code>AWS_SECRET_ACCESS_KEY</code></li>
<li><strong>DigitalOcean:</strong> <code>DO_AUTH_TOKEN=your_token</code></li>
<li><strong>Hetzner:</strong> <code>HETZNER_API_KEY=your_key</code></li>
</ul>
</AlertBlock>
)}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DNS guide omits the required TRAEFIK_DNS_PROVIDER variable

The guide correctly shows per-provider API credentials (CF_DNS_API_TOKEN, AWS_ACCESS_KEY_ID, DO_AUTH_TOKEN, HETZNER_API_KEY), but these are Traefik environment variables. The provider name embedded in traefik.yml is controlled by a separate environment variable — TRAEFIK_DNS_PROVIDER — that must be set in Dokploy's own environment (not Traefik's), because it is read at config-generation time in getDefaultTraefikConfig/getDefaultServerTraefikConfig:

provider: process.env.TRAEFIK_DNS_PROVIDER || "cloudflare",

A user who follows the Route 53, DigitalOcean, or Hetzner rows, sets the correct API credentials in the Traefik Env dialog, but never sets TRAEFIK_DNS_PROVIDER=route53 (or digitalocean / hetzner) in Dokploy's environment will end up with provider: "cloudflare" in traefik.yml — their DNS challenge will call the Cloudflare API with the wrong credentials and silently fail.

The guide should mention that TRAEFIK_DNS_PROVIDER also needs to be set, along with where (Dokploy env vs. Traefik env).

Comment on lines 126 to 131
<DialogTitle>Update Traefik Environment</DialogTitle>
<DialogDescription>
Update the traefik environment variables
Update the traefik environment variables. For wildcard
SSL certificates, configure your DNS provider credentials
below.
</DialogDescription>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dialog description unconditionally references wildcard certificates

The updated DialogDescription always reads "For wildcard SSL certificates, configure your DNS provider credentials below." This text is rendered every time the Traefik Env dialog is opened — including in the existing, non-wildcard flows where users open it from the regular server settings page. It is misleading for users who are not configuring wildcard certificates.

Consider making the description conditional on showDnsGuide:

Suggested change
<DialogTitle>Update Traefik Environment</DialogTitle>
<DialogDescription>
Update the traefik environment variables
Update the traefik environment variables. For wildcard
SSL certificates, configure your DNS provider credentials
below.
</DialogDescription>
<DialogDescription>
{showDnsGuide
? "Update the traefik environment variables. For wildcard SSL certificates, configure your DNS provider credentials below."
: "Update the traefik environment variables."}
</DialogDescription>

@semihanadolu
Copy link
Author

#3941

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working enhancement New feature or request size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant