Cloudflare LetsEncrypt DNS Challenge

This setup uses the Cloudflare DNS-01 challenge to generate Let's Encrypt certificates without opening inbound ports 80 or 443. Instead of serving a validation file over the web, this method proves domain ownership by creating temporary DNS TXT records via the Cloudflare API. Outbound HTTPS (TCP 443) access is still required for Hudu operations and Cloudflare DNS validation.

   No additional packages are needed on the host. The SSL container (SWAG) includes certbot and its DNS plugins, and handles certificate validation and renewal automatically based on your environment settings.

Prerequisites

  • A self-hosted Hudu instance built with the Standard Setup Guide for Self-Hosted
  • A domain with DNS hosted in Cloudflare
  • DNS records already pointing to your Hudu server
  • One of the following Cloudflare credentials:
    • Cloudflare API token (recommended) with Zone → DNS → Edit permissions
    • Cloudflare global API key (not recommended)

If nginx is installed directly on the host, stop and disable it before starting so it does not conflict with the container:

sudo systemctl disable --now nginx

Step 1: Create Cloudflare credentials

Option A: Cloudflare API token (recommended)

  1. Log in to the Cloudflare dashboard
  2. Click your profile icon → My Profile
  3. Select API Tokens
  4. Click Create Token
  5. Choose the Edit Zone DNS template
  6. Under Zone Resources, scope the token to the zone that contains your Hudu domain
  7. Create and copy the token (it is only shown once)
    The token must have Zone → DNS → Edit permission and include the zone for your Hudu domain. A token created in a different Cloudflare account, or scoped to the wrong zone, will fail validation.

Option B: Cloudflare global API key (not recommended)

  1. Log in to the Cloudflare dashboard
  2. Click your profile icon → My Profile
  3. Select API Tokens
  4. View or copy your Global API Key

Step 2: Configure DNS validation in .env

Edit the .env file in your Hudu directory and ensure the following values are set:

PUID=1000
PGID=1000
ONLY_SUBDOMAINS=true
VALIDATION=dns
DNSPLUGIN=cloudflare
EMAIL=example@example.com
STAGING=false

These values tell the SSL container to validate via DNS using its built-in Cloudflare plugin. Replace the example email with your own address, as it receives Let's Encrypt certificate notices.

    Testing your setup? Set STAGING=true to validate against Let's Encrypt's staging environment first. This avoids production rate limits if a validation attempt fails. Once the staging certificate issues successfully, set it back to STAGING=false and restart.

Step 3: Start or restart the Hudu stack

docker compose up -d

For fresh installs, this must happen at least once to initialize the Docker volumes and create the DNS configuration folder:

/var/www/hudu2/config/dns-conf/

Step 4: Configure Cloudflare credentials

Once the stack has started at least once, the Let's Encrypt container automatically creates the Cloudflare credentials file with example values:

/var/www/hudu2/config/dns-conf/cloudflare.ini

Open this file and replace the example values with the credentials from Step 1. Only one option should be active in the file.

Using an API token (recommended)

dns_cloudflare_api_token = YOUR_API_TOKEN

Using a global API key (not recommended)

dns_cloudflare_email = example@example.com
dns_cloudflare_api_key = YOUR_GLOBAL_API_KEY

Secure the file so only the owner can read it:

chmod 600 /var/www/hudu2/config/dns-conf/cloudflare.ini

Step 5: Restart Hudu to apply DNS validation

From your Hudu directory, bring the stack down and back up so the container picks up the new credentials and requests the certificate:

sudo docker compose down && sudo docker compose up -d

 

Troubleshooting

Error: "Unable to determine zone_id for [your domain]"

The container authenticated with Cloudflare but cannot find your domain's zone with the supplied credentials. Check the following:

  • The API token's Zone Resources include the zone for your Hudu domain (or all zones)
  • The token was created in the Cloudflare account that actually hosts the zone
  • The cloudflare.ini file only contains the credential lines for the option you are using, with no extra quotes or leftover example values

After correcting the token or file, restart the stack again per Step 5.

Was this article helpful?
0 out of 0 found this helpful