Skip to content

t1k:web:devops:selfhost-cloudflare

FieldValue
Moduledevops
Version1.31.4
Effortmedium
Tools—

Keywords: access-whitelist, cloudflare access, cloudflare tunnel, cloudflared, deploy, docker compose, expose local app, github actions runner, permission-service, rbac sidebar, self-hosted, systemd runner, zero trust, zone sharing

/t1k:web:devops:selfhost-cloudflare
[runner|tunnel|access|all]

Self-Hosted Deploy behind Cloudflare Tunnel + Access

Section titled “Self-Hosted Deploy behind Cloudflare Tunnel + Access”

Take a Docker-Compose app from a local box to a public, owner-gated URL without a cloud VM: push → systemd GitHub Actions runner → docker compose up -d --build → Cloudflare Tunnel → auth gate (studio-auth for new apps; legacy Cloudflare Access on existing ones) → app.

Every step here is field-proven on a single Arch/Linux host. It is the cheapest path to a real staging/preview URL that you fully control.

Auth default — studio-auth, NOT a new Cloudflare Access app. For a NEW self-hosted app, sign in through studio-auth (docs/studio-auth.md in theonekit-core: a GitHub org-identity sign-in, the studio’s one broker). Existing GitHub org-token checks (ccs-auth-proxy.mjs in theonekit-model-router) stay with their apps. Never send a broad gh token (admin:org/repo) to a server; the chosen credential is a read:org-only GitHub OAuth App token via device flow (planned). A web-frontend gate is planned, not built. Machine callers: GitHub Actions OIDC (exact sub) or a per-caller hashed API key (planned) instead of Access service tokens. Cloudflare Access is legacy, being retired (seat limit, browser login step, security surface): keep existing apps, add no new ones. Plan: plans/261005-zt-github-auth/ in theonekit-core. Legacy/existing-app reference: references/cloudflare-access.md.

Design of the runner/tunnel/Access topology and every security decision stay on a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”). The one bundled script, scripts/access-whitelist-zone.sh, mutates Cloudflare Access and permission-service, so it is NOT delegated to a cheap tier:

StepAgent
(none) — running access-whitelist-zone.sh changes who can reach a hostname; the reasoning-tier session runs it after the zone and emails are confirmedreasoning tier (this session)

Stays reasoning-tier: all of it — a wrong whitelist opens or locks out a production hostname.

Handles: self-hosted GitHub Actions runner (systemd, label-targeted), push-to-deploy via a deploy workflow, cloudflared tunnel ingress + DNS, Cloudflare Access (Zero Trust) apps/policies via API, secure-cookie re-homing, optional permission-service grant mirror for sidebar RBAC, and the recurring gotchas.

Does NOT handle: cloud VM provisioning (GCP/AWS), Kubernetes/ARC pods (wrong tool for a single-host compose deploy — see references/hard-rules.md), app-level RBAC, TLS certs (Cloudflare terminates TLS at the edge). For Workers/R2/D1/serverless, use /t1k:web:devops:core. For one-shot platform deploys (Vercel/Netlify/Fly), use /t1k:web:devops:deploy.

Cost reporting is mandatory. Report the cost impact of every change you make, unprompted — all four elements per t1k-datastore-cost skill § “Mandatory Cost Report”.

IntentRead
“Set up push-to-deploy on my own machine”references/selfhosted-runner.md
“Expose my local app to the internet” / “add a Cloudflare Tunnel”references/cloudflare-tunnel-dns.md
“Gate the site so only I (or my team) can reach it”studio-auth (Auth default above); references/cloudflare-access.md only for an existing Access app
“How should this app get a login?” / “do we need an OAuth client?”studio-auth (Auth default above); a Google OAuth client only via docs/studio-auth.md § “Google identity and Google APIs”; legacy: references/cloudflare-access.md § 0
“Whitelist someone into ONLY one page/zone of an iframe-SPA dashboard”references/cloudflare-access.md § 5b (multi-destination app)
“Verify the Access JWT inside my own app/Worker” / “Cf-Access-Jwt-Assertion”references/cloudflare-access.md § “6. Verifying the Access JWT at the app layer”
“Share a zone/page with a teammate” / “sync CF Access with permission-service” / “drive sidebar RBAC from zone grants”references/permission-service-sync.md
“It deployed but something broke” / 401s / push fails / dashboards vanishedreferences/hard-rules.md
Full greenfield setup, all fourRead all four, in order above
  • A host you control that runs the app via Docker Compose (a reverse proxy like Caddy/nginx fronting the app on one local port — e.g. localhost:<proxy-port>).
  • A Cloudflare account with the target zone (domain) onboarded, plus Zero Trust enabled (free tier: 50 seats; pay-as-you-go: $7/user/month, seats bill by consumers of authentication events — see references/cloudflare-access.md § Zero Trust seats).
  • cloudflared installed on the host; gh CLI + repo admin to register a runner; docker + docker compose.
  • A GitHub repo for the app.
  1. Runner + deploy — register a systemd self-hosted runner with a distinct label, add a deploy.yml that runs on push to your deploy branch and calls your make deploy / docker compose target. Stage a canonical .env from a stable host path into the runner checkout. Re-home cookies to the public host (secure cookies ON). → references/selfhosted-runner.md
  2. Tunnel + DNS — add an ingress rule (hostname → http://localhost:<proxy-port>) to a shared cloudflared config, route DNS (cloudflared tunnel route dns), reload the cloudflared systemd service. → references/cloudflare-tunnel-dns.md
  3. Auth gate — new apps: studio-auth (Auth default above). Legacy only, existing Access hosts — create a self-hosted Access application for the hostname, reuse existing IdPs (GitHub + Email OTP), attach an owner-only policy. Add per-page path-scoped apps later for non-owners. → references/cloudflare-access.md
  4. Verify — unauthenticated request → 302 to the Cloudflare Access login; authenticated → app renders; all app routes return 200 locally behind the proxy.
  • The tunnel means the app’s local port is never exposed directly — only Cloudflare’s edge reaches it. Keep the app bound to localhost/the docker network, never 0.0.0.0 on a public interface.
  • No inbound ports need opening — the tunnel connects outbound-only. If a host firewall is active, leave inbound 80/443 closed.
  • With secure cookies ON, auth works over the tunnel’s HTTPS only; do NOT also serve the app over plain localhost:http to real users (cookie won’t set).
  • Cloudflare Access is the effective gate when the app does not hard-force its own login. If the app does enforce login, Access stacks in front of it (defence in depth), it does not replace it.
  • Treat the Access service-token / API token as a secret: store mode-600 on disk, never paste into chat or commit. Rotate if exposed.