Self-Hosted: Cloudflare Let's Encrypt 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. Certificates are issued and renewed by the certbot container using its Cloudflare DNS plugin, and nginx serves them.

    If your install still runs SWAG (a letsencrypt service using the lscr.io/linuxserver/swag image), follow Migrating an existing SWAG install below instead. The nginx version bundled with SWAG is not patched for the latest nginx vulnerabilities.

Prerequisites

  • A self-hosted Hudu instance built with the Standard Self-Hosted Setup Guide, or a new install following it
  • 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)

For a new install, follow the Standard guide with the changes in this article. You can skip the guide's port check and the plain HTTP placeholder check, and request your certificate with Step 4 below instead of the guide's certbot command.

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: Update the certbot service

In docker-compose.yml, replace the certbot service block with the following. This uses certbot's Cloudflare DNS plugin and mounts the credentials folder.

  certbot:
    image: certbot/dns-cloudflare:v5.7.0
    container_name: certbot
    volumes:
      - /var/www/hudu2/config/etc/letsencrypt:/config/etc/letsencrypt
      - /var/www/hudu2/config/dns-conf:/config/dns-conf:ro

The webroot volume on the nginx service isn't needed for DNS validation, but leaving it in place causes no issues.

Step 3: Add your Cloudflare credentials

Create the credentials folder:

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

Create /var/www/hudu2/config/dns-conf/cloudflare.ini containing the credentials from Step 1. Only one option should be 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 4: Request your certificate

Skip this step if your install already has a certificate. From ~/hudu2, replace docs.yourdomain.com and you@yourdomain.com with your domain and email, then run:

sudo docker compose run --rm certbot certonly --config-dir /config/etc/letsencrypt --dns-cloudflare --dns-cloudflare-credentials /config/dns-conf/cloudflare.ini --dns-cloudflare-propagation-seconds 30 -d docs.yourdomain.com --email you@yourdomain.com --agree-tos --no-eff-email

A successful run confirms the certificate was saved under /config/etc/letsencrypt/live/docs.yourdomain.com/, and saves the DNS settings to your renewal file. For a new install, continue with the Standard guide's Replace the nginx config step, then return to Step 5.

Step 5: Check your renewal settings

Certbot saves the validation method in your renewal file, and renewals reuse it. Confirm it's set to DNS:

sudo grep -E 'authenticator|dns_cloudflare' /var/www/hudu2/config/etc/letsencrypt/renewal/<your domain>.conf

You should see authenticator = dns-cloudflare and a dns_cloudflare_credentials line pointing to /config/dns-conf/cloudflare.ini.

Step 6: Confirm renewal works

This dry run validates against Let's Encrypt's staging environment, so it won't affect your real certificate or count against rate limits:

sudo docker compose run --rm certbot renew --config-dir /config/etc/letsencrypt --dry-run

Step 7: Set up automatic renewal

Certificates are valid for 90 days. If you followed the Standard guide, replace its renewal cron line with this one, which doesn't include the --webroot flags. Open the crontab:

crontab -e

Add this line:

0 3 * * * cd ~/hudu2 && docker compose run --rm certbot renew --config-dir /config/etc/letsencrypt >> /var/log/hudu-certbot-renew.log 2>&1; docker compose exec -T nginx nginx -s reload >> /var/log/hudu-certbot-renew.log 2>&1

It runs daily but only renews within 30 days of expiry. The -T flag is required because cron has no TTY. Test the reload line as cron will run it:

sudo docker compose exec -T nginx nginx -s reload && echo reloaded

Migrating an existing SWAG install

Follow the Swag to NGINX Migration guide with the changes below. Your existing certificate and Cloudflare credentials carry over, so no reissue is needed.

    Don't use the migration guide's renewal steps as written. They use webroot validation, which requires port 80 to be reachable from the internet. If it isn't, Hudu keeps working until the certificate expires and then renewal fails.
  • Before you start, back up your config folder: sudo cp -a /var/www/hudu2/config /var/www/hudu2/config.swag-backup
  • Skip Create the webroot directory.
  • In Edit docker-compose.yml, use the certbot block from Step 2 above in place of the guide's certbot block. Keep the guide's /etc/letsencrypt mount check. Then pull the new certbot image: sudo docker compose pull certbot
  • Your cloudflare.ini from SWAG is already in place. Confirm it contains only your active credential lines and run chmod 600 /var/www/hudu2/config/dns-conf/cloudflare.ini.
  • Complete the guide's Replace default.conf, start nginx, and remove SWAG's renewal hooks as written.
  • Remove leftover DNS provider lines from the renewal file. SWAG adds settings for other DNS providers by default, such as dns_desec_credentials and dns_godaddy_credentials, even when you use Cloudflare. They aren't needed. Leave pref_challs, authenticator, and dns_cloudflare_credentials as they are. If these lines aren't in your file, the command makes no changes.

    sudo cp /var/www/hudu2/config/etc/letsencrypt/renewal/<your domain>.conf /var/www/hudu2/config/etc/letsencrypt/renewal/<your domain>.conf.bak
    sudo sed -i '/dns_desec_credentials/d;/dns_godaddy_credentials/d' /var/www/hudu2/config/etc/letsencrypt/renewal/<your domain>.conf
  • Replace the guide's Confirm renewal works and Set up automatic renewal sections with Steps 5 through 7 above. If you already added the guide's cron line, replace it, since its --webroot flags switch renewal away from DNS.

   The VALIDATION, DNSPLUGIN, ONLY_SUBDOMAINS, and STAGING values in .env are only read by SWAG. You can leave them in place or remove them.

 

Troubleshooting

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

Certbot 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, run the certificate request or renewal command again.

Cloudflare authentication error during renewal

The API token has likely expired or been revoked. Create a new token with Zone → DNS → Edit permission as described in Step 1, update cloudflare.ini, and run the dry run in Step 6 again.

Validation fails with an incorrect TXT record

Cloudflare may need longer to publish the record. Add --dns-cloudflare-propagation-seconds 60 to the dry run command and the cron line, then run the dry run again.

Unsafe permissions warning on cloudflare.ini

Secure the file so only the owner can read it:

chmod 600 /var/www/hudu2/config/dns-conf/cloudflare.ini
Renewal log shows "Hook reported error code 127"

A SWAG renewal hook is still in place. Remove it as described in the Swag to NGINX Migration guide.

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