netstack

Pattern: Docker Service on <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

Overview

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

Fixed components (set up once per site)

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

ZeroTier clients: local name override (split horizon)

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:

Host layout (LinuxServer.io appdata convention)

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:

Where compose files live

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.

Backup

Per-service recipe

1. Compose file (source in the owning repo, deployed to /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).

2. DNS (Cloudflare zone)

CNAME <name> → <tunnel-id>.cfargotunnel.com, proxied. (Or cloudflared tunnel route dns.)

3. Tunnel ingress (Zero Trust → Networks → Tunnels → Public hostnames)

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.

Non-Traefik origins (host services such as Cockpit)

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.

4. Deploy and verify (both paths)

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

5. Document

  1. Add a row to the site repo’s docs/services.md (published at <site>.<domain>).
  2. Add a check to the site’s checks.yml if the service is operational-tier.

Cloudflare Access

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.

Cleanup / audit checklist

Audit commands

# 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)"'