How do I build Caddy with custom DNS modules using xcaddy

title: How do I build Caddy with custom DNS modules using xcaddy
source: https://gemini.google.com/app/37669a96692ada65?utm_source=deepmind.google&utm_medium=referral&utm_campaign=gdm&utm_content=
author:
published:
created: 2026-09-03
description: Gemini conversation with 8 messages
tags:
  - Web

How do I build Caddy with custom DNS modules using xcaddy?

Can I make a github page to access a Caddy proxy server on a high port at my residential COX internet page (port 80 is blocked).

Gemini

No, you cannot directly connect a GitHub Pages site to a Caddy server running on a non-standard port at home.

GitHub Pages only serves static content (HTML, CSS, JavaScript) hosted directly on GitHub's servers and only supports standard HTTP (port 80) and HTTPS (port 443) for custom domains or origin targets. It cannot act as a reverse proxy or forward traffic to an alternate port like 8080 or 8443 at your residential IP address.

However, you can achieve your goal using a few straightforward alternative methods depending on what you want to accomplish:

Method 1: Cloudflare Tunnel (Recommended)

This is the cleanest and most secure way to bypass ISP port blocks (both 80 and 443) without opening any ports on your home router or exposing your home IP address.

How it works: A lightweight daemon (cloudflared) runs on your local machine and creates an outbound encrypted connection to Cloudflare’s edge network.
Setup:
- Point a domain (or free sub-domain) to Cloudflare.
  - Run cloudflared locally and point it at your local Caddy port (e.g., localhost:8443).
  - Cloudflare handles HTTPS on port 443 publicly and routes traffic through the tunnel directly to Caddy.

Method 2: Reverse Proxy via a Cheap VPS

If you want complete control over your traffic routing:

Rent a low-cost virtual private server (VPS).
Point your public domain's DNS to the VPS.
Configure a reverse proxy (Nginx or Caddy) on the VPS listening on standard ports 80/443 that forwards requests to your-home-ip:HIGH_PORT.

Method 3: Static Front-End on GitHub Pages + Client-Side API Calls

If your Caddy server is hosting a backend API rather than rendering HTML pages:

Host your static front-end web app on GitHub Pages.
Have the client-side JavaScript in the browser make fetch/API requests directly to https://your-home-ip-or-domain:HIGH_PORT.
Requirement: Your Caddy server must be configured with proper CORS headers to allow requests originating from your GitHub Pages domain, and it must serve a valid SSL certificate on that high port to prevent mixed-content browser errors.

You

How do I configure CORS headers and HTTPS in Caddy for a local server running on a high port?

Gemini

When running Caddy on an explicit high port (like :8443), Caddy's Automatic HTTPS defaults change because it cannot bind to port 80/443 for standard ACME HTTP-01 challenges.

To serve valid HTTPS on a high port and allow cross-origin requests from a frontend (like GitHub Pages), you need to configure Caddy to use DNS-01 ACME challenges (or local TLS for internal testing) and add explicit CORS headers.

Example Caddyfile

Replace your-domain.com with your actual domain and [https://your-username.github.io](https://your-username.github.io) with your frontend URL:

your-domain.com:8443 {
    # -------------------------------------------------------------
    # 1. TLS / HTTPS Configuration
    # -------------------------------------------------------------
    # Option A: Public Let's Encrypt / ZeroSSL via DNS-01 Challenge
    # (Bypasses blocked ports 80/443. Requires Caddy built with your DNS provider plugin)
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }

    # Option B: Internal / Local testing (Self-Signed / Internal CA)
    # Uncomment the line below if using for local testing only:
    # tls internal

    # -------------------------------------------------------------
    # 2. CORS Headers
    # -------------------------------------------------------------
    header {
        # Allow requests from your frontend origin (GitHub Pages, etc.)
        Access-Control-Allow-Origin "https://your-username.github.io"
        Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
        Access-Control-Allow-Headers "Content-Type, Authorization, X-Requested-With"
        Access-Control-Allow-Credentials "true"

        # Security hardening (optional)
        -Server
    }

    # Handle preflight OPTIONS requests cleanly
    @options {
        method OPTIONS
    }
    respond @options 204

    # -------------------------------------------------------------
    # 3. Proxy / Server Routing
    # -------------------------------------------------------------
    # Forward traffic to your target local backend service
    reverse_proxy localhost:8080
}

Critical Setup Details

1. Obtaining Public SSL Certificates on High Ports (DNS-01 Challenge)

Because port 80 is blocked by your ISP, standard HTTP/TLS-ALPN challenges fail. Caddy must validate domain ownership via your DNS provider's API.

Build Caddy with your DNS plugin: Standard Caddy binaries don't include DNS plugins. Build or download a Caddy binary with your provider's module (e.g., [github.com/caddy-dns/cloudflare](https://github.com/caddy-dns/cloudflare), [github.com/caddy-dns/route53](https://github.com/caddy-dns/route53), or [github.com/caddy-dns/digitalocean](https://github.com/caddy-dns/digitalocean)) using
xcaddy
or the Caddy build service:
```
xcaddy build --with github.com/caddy-dns/cloudflare
```

Environment Variable: Export your API token before starting Caddy:

export CLOUDFLARE_API_TOKEN="your-api-token-here"
caddy run --config /path/to/Caddyfile

2. Browser Mixed-Content & Port Rules

HTTPS Requirement: Modern browsers block requests from an HTTPS page (like GitHub Pages) to an unencrypted HTTP endpoint (http://). Your Caddy high-port endpoint must serve a valid HTTPS certificate.
Exact Origin Match: Standard CORS matching requires the scheme and hostname to match. Ensure Access-Control-Allow-Origin exactly matches the origin origin protocol and domain (e.g., [https://user.github.io](https://user.github.io)). If you need multiple origins during testing, you can dynamically match or use * (though * cannot be used if Access-Control-Allow-Credentials is set to true).

You

How do I build Caddy with custom DNS modules using xcaddy?

Gemini

Building Caddy with custom DNS modules using xcaddy compiles Caddy from source with external Go modules included. This allows Caddy to perform ACME DNS-01 challenges to acquire SSL certificates without needing open HTTP ports (80/443).

Step 1: Install Go and xcaddy

xcaddy requires Go (version 1.22 or newer) installed on your system.

1. Install Go (if not already installed)

Debian/Ubuntu/MX Linux:

sudo apt update
sudo apt install golang-go

Arch Linux / Garuda:
```
sudo pacman -S go
```

2. Install xcaddy

You can install xcaddy using go install:

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

Ensure ~/go/bin is in your PATH so you can execute xcaddy directly:

export PATH=$PATH:$(go env GOPATH)/bin

Step 2: Build Caddy with your DNS Module

Use xcaddy build passed with the --with flag followed by the Go module path for your DNS provider.

Common DNS Providers

Cloudflare:

xcaddy build --with github.com/caddy-dns/cloudflare

Route53 (AWS):

xcaddy build --with github.com/caddy-dns/route53

DigitalOcean:

xcaddy build --with github.com/caddy-dns/digitalocean

DuckDNS:

xcaddy build --with github.com/caddy-dns/duckdns

Namecheap:

xcaddy build --with github.com/caddy-dns/namecheap

Note: You can stack multiple modules in a single build by adding multiple --with flags:
xcaddy build \
  --with github.com/caddy-dns/cloudflare \
  --with github.com/caddy-dns/duckdns

Step 3: Verify the Custom Binary

xcaddy places the freshly compiled binary in your current working directory named caddy.

Verify that your DNS module was successfully linked into the binary:

./caddy list-modules | grep dns

You should see output indicating your module is loaded (e.g., dns.providers.cloudflare).

Step 4: Install and Replace the Binary

Move the compiled binary into your system executable path (e.g., /usr/bin/caddy or /usr/local/bin/caddy) so system service managers or command-line invokers use the custom version:

sudo mv ./caddy /usr/bin/caddy
sudo chmod +x /usr/bin/caddy

Check the installed version:

caddy version

Step 5: Update your Caddyfile and Run

Export your API key or token as an environment variable and configure the tls block in your Caddyfile:

your-domain.com:8443 {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }

    reverse_proxy localhost:8080
}

Run Caddy using your system service or command line:

export CLOUDFLARE_API_TOKEN="your_actual_token_here"
caddy run --config /path/to/Caddyfile

You

How do I set up a systemd service file for Caddy that safely passes DNS API tokens?

Gemini

To safely pass DNS API tokens (like Cloudflare, Route53, or DuckDNS keys) to Caddy via systemd, the best practice is to store the secrets in a dedicated, restricted environment file rather than hardcoding them into the Caddyfile or global system files.

Step 1: Create a Secure Environment File

Create a file specifically for Caddy’s environment variables outside of public visibility (e.g., in /etc/caddy/env).

Open the new environment file with your text editor:
```
sudo mkdir -p /etc/caddy
sudo nano /etc/caddy/env
```

Add your token variables (use key-value pairs without spaces around =):

CLOUDFLARE_API_TOKEN=your_actual_secret_token_here
# MY_OTHER_DNS_TOKEN=xyz123

Lock down permissions so that only root can read the secrets file. Systemd parses EnvironmentFile as root before launching the Caddy process:
```
sudo chown root:root /etc/caddy/env
sudo chmod 600 /etc/caddy/env
```

Step 2: Configure systemd Overrides

Avoid editing /lib/systemd/system/caddy.service directly, as package updates will overwrite your changes. Instead, use systemctl edit to create a persistent drop-in configuration.

Open the systemd override editor:
```
sudo systemctl edit caddy
```
Paste the following configuration into the override file:
```
[Service]
EnvironmentFile=/etc/caddy/env
```
(This tells systemd to load all variables inside /etc/caddy/env as process environment variables before executing Caddy).
Save and exit the editor.

Step 3: Reference Environment Variables in Caddyfile

Inside your Caddyfile, reference the token using the {env.VARIABLE_NAME} syntax:

your-domain.com:8443 {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }

    reverse_proxy localhost:8080
}

Step 4: Apply and Verify

Reload systemd daemon to process the drop-in override:
```
sudo systemctl daemon-reload
```
Restart Caddy to pull in the new environment file:
```
sudo systemctl restart caddy
```
Check the running service status to confirm there are no startup errors:
```
sudo systemctl status caddy
```
Verify Caddy logs to ensure DNS-01 ACME challenge validation succeeds:
```
sudo journalctl -u caddy --no-pager -n 50
```