add cloudflare infrastructure setup guide for tunnels, domains, and token rotation
This commit is contained in:
Hermes
214
methodology/CLOUDFLARE-SETUP.md
Normal file
214
methodology/CLOUDFLARE-SETUP.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Cloudflare Infrastructure Setup
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
Browser ──► Cloudflare (orange cloud) ──► Tunnel ──► cloudflared ──► Traefik:8081
|
||||
│
|
||||
(tunnel entrypoint)
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
secureweb tunnel
|
||||
(direct internet) (via tunnel)
|
||||
:443 :8081
|
||||
LetsEncrypt plain HTTP
|
||||
```
|
||||
|
||||
All external traffic goes through Cloudflare Tunnel. Traefik serves as the internal reverse proxy, routing by Host header. Traefik's LetsEncrypt certs exist for LAN/direct access but aren't used externally (Cloudflare edge terminates TLS for visitors).
|
||||
|
||||
## Active Stack
|
||||
|
||||
| Component | Location | Notes |
|
||||
|---|---|---|
|
||||
| Tunnel name | `home` | Created at Cloudflare Zero Trust → Networks → Tunnels |
|
||||
| Tunnel ID | `c29295c5-946a-4ddf-bdfe-7eafcd74faa3` | Visible in dashboard |
|
||||
| Token | `.env` `TUNNEL_TOKEN=...` | Used by cloudflared to authenticate |
|
||||
| cloudflared | production-1 Docker container | Runs with `--restart unless-stopped` |
|
||||
| Traefik | production-1 Docker container | Ports 80, 443, 8080, 8082 |
|
||||
| Traefik entrypoints | `web` (:80→redirect), `secureweb` (:443, TLS), `tunnel` (:8081), `metrics` (:8082) | |
|
||||
| Traefik config | `/docker/appdata/traefik/traefik.yaml` | |
|
||||
| Compose file | `/docker/compose/docker-compose.yaml` | cloudflared service defined but runs standalone due to interpolation issues |
|
||||
| Traefik labels | Per-service in docker-compose.yaml | Pattern: `entrypoints=tunnel`, `Host(`subdomain.gharbeia.net`)` |
|
||||
|
||||
## 1. Adding a Second Domain
|
||||
|
||||
Example: adding `example.com` alongside `gharbeia.net`.
|
||||
|
||||
### Step 1: Cloudflare DNS
|
||||
|
||||
1. Go to Cloudflare Dashboard → Add site → enter `example.com`
|
||||
2. Cloudflare scans existing DNS records — verify and continue
|
||||
3. Change nameservers at your registrar to Cloudflare's
|
||||
4. Wait for DNS to propagate
|
||||
|
||||
### Step 2: Cloudflare Tunnel — add hostname
|
||||
|
||||
1. **Zero Trust** → **Networks** → **Connectors** → **Cloudflare Tunnels**
|
||||
2. Select tunnel **home** → **Edit**
|
||||
3. Click **Add a public hostname**
|
||||
4. Set:
|
||||
- **Subdomain:** `*`
|
||||
- **Domain:** `example.com`
|
||||
- **Service Type:** HTTP
|
||||
- **URL:** `traefik:8081`
|
||||
5. Save
|
||||
|
||||
Cloudflare DNS will automatically create a wildcard CNAME for `*.example.com` pointing to `c29295c5-946a-4ddf-bdfe-7eafcd74faa3.cfargotunnel.com`.
|
||||
|
||||
### Step 3: Traefik — update cert resolver
|
||||
|
||||
Cloudflare wildcard certs only cover `*.gharbeia.net`. For `*.example.com`, either:
|
||||
|
||||
**Option A: Add to Traefik's ACME config**
|
||||
|
||||
In `/docker/appdata/traefik/traefik.yaml`, in `certificatesResolvers.letsencrypt.acme`:
|
||||
```yaml
|
||||
dnsChallenge:
|
||||
provider: cloudflare
|
||||
resolvers:
|
||||
- 1.1.1.1:53
|
||||
- 1.0.0.1:53
|
||||
propagation:
|
||||
delayBeforeChecks: 120s # increase for wildcards
|
||||
```
|
||||
|
||||
Then in `entryPoints.secureweb.http.tls.domains`:
|
||||
```yaml
|
||||
domains:
|
||||
- main: gharbeia.net
|
||||
sans:
|
||||
- "*.gharbeia.net"
|
||||
- main: example.com
|
||||
sans:
|
||||
- "*.example.com"
|
||||
```
|
||||
|
||||
**Important:** Before ACME DNS challenge can succeed for wildcard domains proxied via Cloudflare, you MUST create a DNS-only placeholder record for `_acme-challenge` to break the wildcard:
|
||||
|
||||
Go to Cloudflare DNS → Add record:
|
||||
- **Type:** A
|
||||
- **Name:** `_acme-challenge`
|
||||
- **Content:** `127.0.0.1`
|
||||
- **Proxy:** DNS-only (gray cloud)
|
||||
|
||||
Without this, the proxied wildcard CNAME intercepts `_acme-challenge.*` queries and LetsEncrypt can't verify the TXT challenge records.
|
||||
|
||||
**Option B: Skip HTTPS cert for now**
|
||||
|
||||
If the second domain doesn't need Traefik's own cert (i.e., Cloudflare edge certs are sufficient), no Traefik changes needed. The tunnel handles everything.
|
||||
|
||||
### Step 4: Add Traefik labels
|
||||
|
||||
For each service on the new domain, add Traefik labels in docker-compose.yaml:
|
||||
```yaml
|
||||
labels:
|
||||
- traefik.enable=true
|
||||
- traefik.http.routers.servicename.rule=Host(`subdomain.example.com`)
|
||||
- traefik.http.routers.servicename.entrypoints=tunnel
|
||||
- traefik.http.services.servicename.loadbalancer.server.port=3000
|
||||
```
|
||||
|
||||
Then restart the container to pick up labels (compose or docker run depending on env state).
|
||||
|
||||
---
|
||||
|
||||
## 2. Security Panic — Changing All Tokens and Settings
|
||||
|
||||
### Step 1: Cloudflare API Token
|
||||
|
||||
1. Go to Cloudflare Dashboard → **My Profile** → **API Tokens**
|
||||
2. **Delete** the old token
|
||||
3. **Create Token** → **Edit zone DNS** template:
|
||||
- Permissions: Zone → DNS → Edit
|
||||
- Zone Resources: Include → Specific zone → `gharbeia.net`
|
||||
- TTL: No expiration (or set a reasonable one)
|
||||
4. Copy the new token
|
||||
|
||||
### Step 2: Update .env on production-1
|
||||
|
||||
```bash
|
||||
ssh production-1
|
||||
# Edit the token
|
||||
sed -i "s|^CLOUDFLARE_DNS_API_TOKEN=.*|CLOUDFLARE_DNS_API_TOKEN=<new-token>|" /docker/compose/.env
|
||||
```
|
||||
|
||||
### Step 3: Restart Traefik
|
||||
|
||||
Traefik runs standalone (not under compose). Restart it with the new token:
|
||||
|
||||
```bash
|
||||
docker rm -f traefik
|
||||
docker run -d --name traefik --restart unless-stopped --network networking \
|
||||
-p 80:80 -p 443:443 -p 8080:8080 -p 8082:8082 \
|
||||
-e CF_DNS_API_TOKEN="<new-token>" \
|
||||
-e TZ="America/New_York" \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock:ro \
|
||||
-v /docker/appdata/logs/traefik:/var/log \
|
||||
-v /docker/appdata/traefik:/etc/traefik \
|
||||
-v /docker/appdata/traefik/letsencrypt:/letsencrypt \
|
||||
traefik:latest
|
||||
```
|
||||
|
||||
Traefik will automatically renew its LetsEncrypt cert with the new token.
|
||||
|
||||
### Step 4: Cloudflare Tunnel Token
|
||||
|
||||
If you also rotate the tunnel token:
|
||||
|
||||
1. Go to **Zero Trust** → **Networks** → **Tunnels** → **home**
|
||||
2. Click the three dots → **Recreate token**
|
||||
3. Copy the new token
|
||||
|
||||
On production-1:
|
||||
```bash
|
||||
docker rm -f cloudflared
|
||||
docker run -d --name cloudflared --restart unless-stopped --network networking \
|
||||
-v /docker/appdata/cloudflared:/home/nonroot/.cloudflared \
|
||||
cloudflare/cloudflared:latest tunnel --no-autoupdate run --token "<new-token>"
|
||||
```
|
||||
|
||||
Also update the `.env` file:
|
||||
```
|
||||
TUNNEL_TOKEN=<new-token>
|
||||
```
|
||||
|
||||
### Step 5: Verify everything works
|
||||
|
||||
```bash
|
||||
# Check cloudflared is connected
|
||||
docker logs cloudflared --tail 5 | grep "Registered tunnel connection"
|
||||
|
||||
# Check Traefik is running and has routes
|
||||
docker logs traefik --tail 10 | grep "Register"
|
||||
|
||||
# Test end-to-end
|
||||
curl -sI https://git.gharbeia.net/ | head -5
|
||||
# Should return HTTP/2 200
|
||||
```
|
||||
|
||||
### Step 6: Rotate other secrets (if needed)
|
||||
|
||||
Other credentials in `.env` that may need rotation:
|
||||
- `AUTHENTIK_SECRET_KEY` — generate new: `openssl rand -base64 60 | tr -d '\n'`
|
||||
- `POSTGRESQL_PASSWORD` — generate new
|
||||
- `EMAIL_PASSWORD` — Fastmail app password
|
||||
- `GITEA_TOKEN` — Gitea settings → Applications
|
||||
- `OPENROUTER_API_KEY` — OpenRouter dashboard
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Cert renewal fails with "Invalid format for Authorization header"
|
||||
The Cloudflare API token in `CF_DNS_API_TOKEN` is wrong or expired. Generate a new one and restart Traefik.
|
||||
|
||||
### Cert renewal stuck on "Waiting for DNS record propagation"
|
||||
Likely the proxied wildcard CNAME is intercepting `_acme-challenge` subdomain. Add a DNS-only A record for `_acme-challenge` → `127.0.0.1` in Cloudflare DNS to break the wildcard.
|
||||
|
||||
### Tunnel shows 502 Bad Gateway
|
||||
- Check cloudflared logs: `docker logs cloudflared --tail 10`
|
||||
- If `connection refused` → Traefik isn't listening on the expected port
|
||||
- If `tls: unrecognized name` → SNI mismatch (revert to HTTP mode in tunnel config)
|
||||
|
||||
### Adding a new service
|
||||
1. Add Traefik labels to the service in docker-compose.yaml
|
||||
2. If the container was started without labels, recreate it with `docker run` including `-l` flags (compose may fail due to .env interpolation issues)
|
||||
3. The tunnel wildcard already catches `*.gharbeia.net` — no tunnel changes needed
|
||||
Reference in New Issue
Block a user