V6.0 Phase 3 - Add cloudflare tunnel. Remote access to app via the tunnel now working.

docs/cloudflare_tunnel_access.md

@@ -0,0 +1,60 @@
+# Cloudflare Tunnel and Access Setup (V6.0 Phase 3)
+
+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:
+
+```bash
+docker compose --env-file .env.production -f docker-compose.production.yml up -d --build
+```
+
+Validate tunnel container:
+
+```bash
+docker compose --env-file .env.production -f docker-compose.production.yml logs cloudflared
+```
+
+## 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.

docs/production-runbook.md

@@ -25,6 +25,7 @@ This runbook is the operational checklist for releasing and monitoring the trans
    - `/healthz` responds `200`
    - if `RUN_EMBEDDED_WORKER=true`, `worker.state` is `running`
    - if `RUN_EMBEDDED_WORKER=false`, validate `worker` container is healthy/running in Compose
+   - validate `cloudflared` logs show active tunnel routes and no ingress errors
 3. Execute one smoke workflow:
    - create a document/job with at least one source
    - verify terminal job outcome updates
@@ -86,6 +87,13 @@ This runbook is the operational checklist for releasing and monitoring the trans
 2. Confirm failures are category-aligned (`external`/`timeout`/`internal`).
 3. Triage whether issue is source quality, provider, or runtime regression.
 
+### Cloudflare ingress/access failure
+
+1. Check `cloudflared` container logs for ingress parse, DNS, or auth failures.
+2. Confirm `deploy/cloudflared/config.yml` tunnel UUID and hostname mappings are correct.
+3. Confirm `deploy/cloudflared/credentials.json` matches the tunnel configured in Cloudflare.
+4. Confirm Cloudflare Access app policy includes the intended identity/group for that hostname.
+
 ## 6. Dependency upgrade policy
 
 Dependencies are declared in `pyproject.toml` and resolved through the committed

docs/v6_0_hosting_migration_plan.md

@@ -49,6 +49,11 @@ Implemented workflow references:
 2. Apply Cloudflare Access policies for identity-gated remote access.
 3. Keep non-required administrative/internal surfaces LAN-only unless explicitly approved.
 
+Implemented workflow references:
+
+- `deploy/cloudflared/config.yml.example`
+- `docs/cloudflare_tunnel_access.md`
+
 ## 3.4 Backup, restore, rollback
 
 1. Define backup schedule, retention, and artifact naming/versioning.