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.
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 → Editpermissions - Cloudflare global API key (not recommended)
-
Cloudflare API token (recommended) with
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 nginxStep 1: Create Cloudflare credentials
Option A: Cloudflare API token (recommended)
- Log in to the Cloudflare dashboard
- Click your profile icon → My Profile
- Select API Tokens
- Click Create Token
- Choose the Edit Zone DNS template
- Under Zone Resources, scope the token to the zone that contains your Hudu domain
- Create and copy the token (it is only shown once)
Option B: Cloudflare global API key (not recommended)
- Log in to the Cloudflare dashboard
- Click your profile icon → My Profile
- Select API Tokens
- 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:roThe 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-confCreate /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_TOKENUsing a global API key (not recommended)
dns_cloudflare_email = example@example.com
dns_cloudflare_api_key = YOUR_GLOBAL_API_KEYSecure the file so only the owner can read it:
chmod 600 /var/www/hudu2/config/dns-conf/cloudflare.iniStep 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-emailA 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>.confYou 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-runStep 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 -eAdd 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>&1It 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 reloadedMigrating 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.
- 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.inifrom SWAG is already in place. Confirm it contains only your active credential lines and runchmod 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_credentialsanddns_godaddy_credentials, even when you use Cloudflare. They aren't needed. Leavepref_challs,authenticator, anddns_cloudflare_credentialsas 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
--webrootflags 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
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.inifile 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.
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.
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.
Secure the file so only the owner can read it:
chmod 600 /var/www/hudu2/config/dns-conf/cloudflare.ini
A SWAG renewal hook is still in place. Remove it as described in the Swag to NGINX Migration guide.