Caddy & Cloudflare Integration
Relevant source files
The following files were used as context for generating this wiki page:
Caddy and Cloudflare together manage the networking, security, and SSL termination for PuppyPad. Caddy acts as a reverse proxy that sits in front of the Express application, handling all incoming traffic for puppypad.org and its member subdomains. Cloudflare provides DNS management and acts as a security barrier, supporting the automated issuance of wildcard SSL certificates.
The integration utilizes a DNS-01 challenge to obtain a single wildcard certificate for the entire domain. This replaces the previous "on-demand" TLS method, which issued certificates per subdomain on first visit and was susceptible to Let's Encrypt rate limits. Sources: PLAN.md:14-25, PLAN.md:78-86, README.md:118-124
System Architecture
The traffic flow moves from the user through Cloudflare's DNS to the Caddy server, which then proxies the request to the Node.js Express application.
The diagram shows the request path and the background DNS-01 challenge process for SSL certificate issuance. Sources: PLAN.md:14-25, PLAN.md:78-86
DNS Configuration
PuppyPad requires specific DNS records at Cloudflare for the application to function correctly. Both the root domain and the wildcard subdomain must point to the VPS IP address.
Required Records
| Record Type | Name | Content | Proxy Status |
|---|---|---|---|
| A | puppypad.org | VPS IPv4 | DNS Only (Grey Cloud) |
| AAAA | puppypad.org | VPS IPv6 (Optional) | DNS Only (Grey Cloud) |
| A | *.puppypad.org | VPS IPv4 | DNS Only (Grey Cloud) |
| TXT | _psl.puppypad.org | PSL Entry Verification | N/A |
Sources: PLAN.md:173-176, README.md:118-121
Important Note on Proxy Status: You must keep the Cloudflare records set to "DNS only" (grey cloud). If the Cloudflare proxy is enabled, every visitor appears as a Cloudflare IP to the Express app. This breaks per-IP rate limits unless the application is specifically configured to read the CF-Connecting-IP header. Sources: PLAN.md:83-86, README.md:148-151
Automated TLS Management
Caddy uses the caddy-dns/cloudflare plugin to automate certificate management. It performs a DNS-01 challenge using a Cloudflare API token to prove domain ownership without requiring an open port 80 for HTTP-01 challenges.
SSL Issuance Process
The sequence diagram illustrates the automated DNS-01 challenge workflow. Sources: PLAN.md:78-86, README.md:144-147
Environment Configuration
The integration depends on several environment variables defined in .env and .env.caddy. Caddy-specific credentials are isolated to prevent the main application from accessing DNS management tokens.
Configuration Variables
| Variable | File | Description |
|---|---|---|
BASE_DOMAIN | .env | The root domain (e.g., puppypad.org). |
ACME_EMAIL | .env | Email address for Let's Encrypt account notifications. |
CF_API_TOKEN | .env.caddy | Cloudflare API token with "Edit zone DNS" permissions. |
BASE_URL | .env | The full origin URL (e.g., https://puppypad.org). |
Sources: PLAN.md:177-180, README.md:122-127, src/server.js:18-35
Security and Isolation
To enhance browser-side security, the project recommends submitting puppypad.org to the Public Suffix List (PSL). Once listed, browsers treat each name.puppypad.org as its own top-level site. This provides the following benefits:
- Prevents "cookie-tossing" between member subdomains.
- Isolates browser storage (localStorage, IndexedDB) per member.
- Strengthens the security boundary for member-written JavaScript.
The application already uses the __Host- prefix for the session cookie (__Host-sid) as a mitigation, which prevents subdomains from reading or overwriting the login cookie. Sources: PLAN.md:87-93, README.md:152-156, src/server.js:37-38
Integration Summary
The Caddy and Cloudflare integration provides a robust, scalable front-end for PuppyPad. By moving to a wildcard certificate system via DNS-01 challenges, the platform can support thousands of member subdomains without hitting Let's Encrypt rate limits or requiring complex on-demand certificate logic. The architecture prioritizes security through isolated environment variables and the future implementation of the Public Suffix List. Sources: PLAN.md:78-86, PLAN.md:204-206, README.md:118-124