t1k:web:devops:selfhost-cloudflare
| Field | Value |
|---|---|
| Module | devops |
| Version | 1.31.4 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/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.
Executed by
Section titled “Executed by”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:
| Step | Agent |
|---|---|
(none) — running access-whitelist-zone.sh changes who can reach a hostname; the reasoning-tier session runs it after the zone and emails are confirmed | reasoning 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”.
Decision Tree
Section titled “Decision Tree”| Intent | Read |
|---|---|
| “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 vanished | references/hard-rules.md |
| Full greenfield setup, all four | Read all four, in order above |
Prerequisites
Section titled “Prerequisites”- 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). cloudflaredinstalled on the host;ghCLI + repo admin to register a runner;docker+docker compose.- A GitHub repo for the app.
Workflow (greenfield “all”)
Section titled “Workflow (greenfield “all”)”- Runner + deploy — register a systemd self-hosted runner with a distinct label, add a
deploy.ymlthat runs on push to your deploy branch and calls yourmake deploy/docker composetarget. Stage a canonical.envfrom a stable host path into the runner checkout. Re-home cookies to the public host (secure cookies ON). →references/selfhosted-runner.md - Tunnel + DNS — add an ingress rule (
hostname → http://localhost:<proxy-port>) to a sharedcloudflaredconfig, route DNS (cloudflared tunnel route dns), reload thecloudflaredsystemd service. →references/cloudflare-tunnel-dns.md - 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 - Verify — unauthenticated request → 302 to the Cloudflare Access login; authenticated → app renders; all app routes return 200 locally behind the proxy.
Security
Section titled “Security”- 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, never0.0.0.0on 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:httpto 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.