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. Outbound HTTPS (TCP 443) access is required for Hudu operations and Cloudflare DNS validation.

This method validates domain ownership by creating temporary DNS TXT records via the Cloudflare API.

Prerequisites

• Self-hosted Hudu instance using the Standard Self-Hosted Setup Guide

• 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)

• Disable nginx if already installed:

sudo systemctl disable 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. Scope the token to the required zone(s)

7. Create and copy the token (shown once)

Required permission:

Zone → DNS → Edit

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

Step 3: Install the Certbot DNS Plugin

sudo apt-get install python3-certbot-dns-cloudflare

Step 4: Start or Restart the Hudu Stack

docker compose up -d

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

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

Step 5: Configure Cloudflare Credentials

After the Hudu stack has been 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 your own Cloudflare credentials.

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:

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

Step 6: Restart Hudu to Apply DNS Validation

Bring Docker down and back up by running:

cd ~/hudu2 && sudo docker compose down && sudo docker compose up -d