<name>.<domain> (Cloudflare Tunnel → Traefik)Pattern type: Service deployment
Applies to: Any federation site that runs Docker + Traefik + a cloudflared tunnel (reference site: cf, domain cat9.me)
Related: site-repo-flow-pattern (rebuild/BMR, version pinning), cloudflare-tunnel-monitoring-pattern, site-docs-generator-pattern
One tunnel, one reverse proxy, one wildcard cert. Adding a service is: a compose file with Traefik labels, a DNS CNAME, and a tunnel ingress entry. Nothing else.
Browser → Cloudflare edge (proxied CNAME) → tunnel → cloudflared container
→ https://traefik:443 (Host header preserved) → Traefik router by Host(`<name>.<domain>`)
→ backend container on the `proxy` docker network
| Component | Rule |
|---|---|
| Docker network | External network proxy. Traefik, cloudflared and every routed service join it. |
| Traefik | Docker provider, exposedByDefault: false. Entrypoints http (→ https redirect) and https. |
| TLS | Wildcard *.<domain> from the cloudflare ACME DNS-challenge resolver (token in a Docker secret/.env, never in compose). |
| cloudflared | tunnel run, token from .env (TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}), on the proxy network. |
| Tunnel ingress | Remotely managed (Zero Trust dashboard / API). |
Cloudflare’s filters flag/challenge traffic coming from ZeroTier-network clients. To avoid that, ZeroTier clients resolve <name>.<domain> locally (hosts file or local DNS) to the Docker host’s ZeroTier IP (cf: 10.147.17.176) and hit Traefik directly on 443, using the same wildcard cert. Public clients use the Cloudflare tunnel path above.
ZeroTier client → local override → 10.147.17.176:443 → Traefik → container
Public client → Cloudflare DNS → tunnel → https://traefik:443 → Traefik → container
Consequences:
pile.cat9.me alias) differ from Cloudflare’s; audit Cloudflare via the API, not dig from a ZeroTier host.curl --resolve <name>.<domain>:443:<zt-ip> https://<name>.<domain> and the public path from a non-ZeroTier network.Every service lives in one folder under a single appdata root. Default root: /opt/appdata (override per host with DATA_ROOT).
/opt/appdata/<name>/
compose.yml # copied from the owning repo (see "Where compose files live")
.env # secrets, chmod 600, never in git
config/ # app configuration (bind mount)
data/ # app state: databases, uploads (bind mount)
Rules:
~/code holds git repos only. No service data, no secrets, no live compose files.${DATA_ROOT:-/opt/appdata}/<name>/. Named volumes are only for rebuildable output (generated sites, caches).sudo mkdir -p /opt/appdata && sudo chown nsadmin:nsadmin /opt/appdata (top level only, not -R). Each /opt/appdata/<name>/ is owned by the user its container runs as (nsadmin for PUID=1000 images; root for images that run as root; a fixed UID for databases). A recursive chown of the whole tree breaks those.PUID/PGID (the service owner, e.g. 1000:1000) where the image supports it, so files in appdata are owned by a normal user./media/<share> and are not part of appdata./opt/appdata/traefik/ holds config/traefik.yaml, config/dynamic/, acme.json (600) and logs/.| What | Source of truth | Deployed to |
|---|---|---|
| App with its own repo (e.g. tte) | deploy/docker-compose.yml + deploy/example.env in that repo |
/opt/appdata/<name>/compose.yml |
| Site service (site-status, wip-site) | ops/services/<name>/ in the site repo (cf, wip) |
/opt/appdata/<name>/compose.yml |
| Infrastructure (traefik, cloudflared, gitea, portainer) | ops/services/<name>/ in the site repo |
/opt/appdata/<name>/compose.yml |
A separate catch-all docker-compose repo is not used: compose files are versioned with the thing they deploy. Use one compose file per service; the repo-root docker-compose.yml (if any) is for offline/local use (e.g. a meet with no internet: published port, no Traefik, no tunnel) and deploy/docker-compose.yml is for the tunnel/Traefik deployment.
/opt/appdata (not ~/code). Exclude */logs/, caches and rebuildable named volumes.pg_dump for Postgres, sqlite3 <db> ".backup <file>" for SQLite, or docker compose stop for the copy window..env files and acme.json are secrets: include them in the encrypted backup only./opt/appdata/<name>/compose.yml)No ports: publishing. Traefik is the only entry point.
services:
<name>:
image: <image>
container_name: <name>
restart: unless-stopped
networks: [proxy]
volumes:
- ${DATA_ROOT:-/opt/appdata}/<name>/data:/app/data
labels:
- traefik.enable=true
- traefik.docker.network=proxy
- traefik.http.routers.<name>.rule=Host(`<name>.<domain>`)
- traefik.http.routers.<name>.entrypoints=https
- traefik.http.routers.<name>.tls=true
- traefik.http.routers.<name>.tls.certresolver=cloudflare
- traefik.http.services.<name>.loadbalancer.server.port=<container port>
networks:
proxy:
external: true
Pin the image tag (image: <image>:<version>, version from .env). No :latest; see site-repo-flow-pattern. Updates are a deliberate act.
Two compose files per app when it must also run offline: the repo-root docker-compose.yml is for local/offline events (published port, no Traefik, no tunnel); deploy/docker-compose.yml is the tunnel/Traefik deployment (this recipe) and is the one copied to /opt/appdata/<name>/compose.yml.
Multi-container projects: only the web-facing container gets labels. Name routers/services <name> (no -secure suffixes, no duplicate http router; the entrypoint redirect handles port 80).
CNAME <name> → <tunnel-id>.cfargotunnel.com, proxied. (Or cloudflared tunnel route dns.)
| Hostname | Service | Origin request |
|---|---|---|
<name>.<domain> |
https://traefik:443 |
No TLS Verify = on |
Origin request settings (required): Edit the public hostname → Additional application settings → TLS → Origin Server Name = <name>.<domain>. This is a separate setting from the public “Full hostname” field. cloudflared connects to traefik but the cert is *.<domain>, so without it the TLS name check fails and Cloudflare returns 502. Fallback: No TLS Verify = on (less strict; avoid unless needed). Leave HTTP Host Header unset so Traefik sees the original Host. Do not turn TLS off; the origin is https://traefik:443. API field: originRequest.originServerName.
Rule order matters: ingress rules are matched top to bottom, first match wins. A wildcard rule (*.<domain>) matches every hostname listed below it, so those rules never run. Keep no wildcard rule (preferred), or put it last, just above the final http_status:404. New hostnames go anywhere above it.
Always target the container name traefik on the proxy network. Never use a host IP such as https://192.168.x.x; it breaks when the host’s LAN address changes.
A service running on the host (not a container) cannot use the container name. Preferred: add extra_hosts: ["host.docker.internal:host-gateway"] to the cloudflared container and use http://host.docker.internal:<port>. Acceptable: the host’s ZeroTier IP (stable, but the route then depends on ZeroTier). Never the LAN IP. Origin Server Name has no effect on http:// origins. Admin tools like Cockpit must sit behind Cloudflare Access.
mkdir -p /opt/appdata/<name>/data
cd /opt/appdata/<name> && docker compose up -d
docker logs traefik 2>&1 | grep <name>
# Public path (Cloudflare tunnel) - run from a host WITHOUT a local override for <name>:
curl -sI https://<name>.<domain> # expect 200/302, server: cloudflare
# ZeroTier path (direct to Traefik):
curl -sI --resolve <name>.<domain>:443:<zt-ip> https://<name>.<domain>
# Tunnel errors:
docker logs --tail 20 cf-cat9me # check ingressRule=N and originService for the failing request
docs/services.md (published at <site>.<domain>).checks.yml if the service is operational-tier.Every hostname is locked behind Cloudflare Access by default (wildcard lockdown app); only read-only /status.json and /health paths are opened. Full design, policies, sessions and the verify-access.sh check: cloudflare-federation-access-pattern. Adding a hostname = tunnel route + DNS + a line in the site’s access-policy.conf. Machine-readable endpoints (/status.json, /health, registry /v2/) get separate path-specific Bypass applications; Cloudflare matches the most specific application first. Record which hostnames are covered in the site’s services doc. When testing the public path, a 302 to *.cloudflareaccess.com means the tunnel works and Access is answering.
https://traefik:443 (or http://traefik:80), except deliberate non-Traefik origins, which must be listed in the site’s services doc with a reason.traefik.enable=true has a DNS record and ingress entry.:latest image tags; versions pinned..env (git-ignored, 600)./opt/appdata/traefik/config), one source of truth./opt/appdata/<name>/, not ~/code and not a hidden named volume.docker-compose repo.# Router rules of running containers
docker ps -q | xargs -I{} docker inspect {} --format ' enabled'
# Tunnel ingress (account token with Cloudflare Tunnel:Read)
curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/cfd_tunnel/$TUNNEL_ID/configurations \
| jq -r '.result.config.ingress[] | "\(.hostname) -> \(.service)"'
# DNS records (zone token with DNS:Read)
curl -s -H "Authorization: Bearer $CF_ZONE_READ_TOKEN" \
"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?per_page=200" \
| jq -r '.result[] | "\(.type) \(.name) -> \(.content)"'