transcription/docs/cloudflare_tunnel_access.md

Cloudflare Tunnel and Access Setup

This guide defines the repository-supported setup for exposing app and selected LAN services through Cloudflare Tunnel with Cloudflare Access protection.

1. Files used by this deployment

1. deploy/cloudflared/config.yml (local copy from config.yml.example)
2. .env.production (CLOUDFLARE_TUNNEL_TOKEN)
3. docker-compose.production.yml (cloudflared service reads token + mounts config)

Do not commit config.yml or .env.production.

2. Configure cloudflared

1. Copy deploy/cloudflared/config.yml.example to deploy/cloudflared/config.yml.
2. Update hostname -> service mappings in ingress.
3. Keep the final catch-all ingress http_status:404.
4. Set CLOUDFLARE_TUNNEL_TOKEN in .env.production.

Example app route:

• transcription.example.com -> http://app:8000

Optional generic remote-access routes:

• homeassistant.example.com -> http://<home-assistant-lan-ip>:8123
• pihole.example.com -> http://<pihole-lan-ip>:80

3. Cloudflare Access policy baseline

Create one Access app policy per exposed hostname:

1. Include: your allowed identities/groups only.
2. Exclude: none by default.
3. Require: identity provider login (and MFA if available).

Recommended baseline:

• App endpoint (transcription.*): your admin identity set.
• Other internal endpoints (homeassistant.*, pihole.*, etc.): explicit least-privilege groups.

4. Startup

Start production stack:

docker compose --env-file .env.production -f docker-compose.production.yml up -d --build

Validate tunnel container:

docker compose --env-file .env.production -f docker-compose.production.yml logs cloudflared

LXC/proxied-network note:

• The cloudflared service is pinned to --protocol http2 with explicit DNS resolvers (1.1.1.1, 1.0.0.1) in docker-compose.production.yml.
• This avoids environments where Docker's embedded resolver (127.0.0.11) cannot resolve region*.v2.argotunnel.com, which causes connector precheck failure and tunnel shutdown.
• If tunnel status is still down, verify host/container egress for DNS and TCP 443 to api.cloudflare.com and *.argotunnel.com.

5. Security notes

• Keep postgres and other internal-only services off public hostnames unless required.
• Use distinct hostnames per service; avoid path-based multiplexing for unrelated admin surfaces.
• Rotate CLOUDFLARE_TUNNEL_TOKEN and Access policy memberships on a regular schedule.