Cloudflare

Create the tunnelCopy Anchor Link

Dashboard → Networking → Tunnels → Create a tunnel, and name it. The next page shows an installation command per operating system: copy only the token from it (the long string starting with eyJ) and do not run the command, since docker-compose.yml runs cloudflared. Keep it in a file only you can read, or in Doppler as CLOUDFLARE_TUNNEL_TOKEN (The tunnel token). Anyone with the token can run your tunnel; the tunnel's Overview → Refresh token replaces it.

Deploy the web app's WorkerCopy Anchor Link

From a checkout, with an account-owned API token from the Edit Cloudflare Workers template in CLOUDFLARE_API_TOKEN and your account ID in CLOUDFLARE_ACCOUNT_ID. First set the route in frontend/wrangler.jsonc to your domain ("pattern": "analytics.example.com/*", "zone_name": "example.com"), then:

cd frontend && bun install --frozen-lockfile && bun run deploy:cloudflare

wrangler deploy builds the web app and the public site first, uploads them as static assets, and creates the route. The developer documentation deploys the same way from pilotfox-documentation/, on a host name of its own (it uses the root of its origin). The repository's workflow backend/ci/github/workflows/workers.yml can deploy both on every push.

Send the API's paths to the tunnelCopy Anchor Link

Create three routes without a Worker, once: <your domain>/api/*, <your domain>/.well-known/* and <your domain>/maps/* (Workers Routes in the dashboard, or the API's "Create Route" with only a pattern). The most specific route wins, and a route without a Worker sends its requests to the zone's DNS record, which step 4 points at the tunnel.

Point the tunnel at the APICopy Anchor Link

Once the server runs (Start the stack) and the dashboard shows the tunnel connected: the tunnel's Routes tab → Add route → Published application, your domain, no path, Service URL http://api:3001. Cloudflare creates the proxied DNS record that points the name at the tunnel; an existing A or AAAA record of the same name has to go first.

Set the zone's settingsCopy Anchor Link

• SSL/TLS → Edge Certificates → Always Use HTTPS on. The Worker and the API send HSTS themselves.

• Rules → Settings → Managed Transforms: Add visitor location headers on, so visitors get a region, city and time zone, not only a country. Leave Remove visitor IP headers off: it removes CF-Connecting-IP, and every visitor would then share a Cloudflare server's address (sessions, rate limits and IP exclusions all key on it).

• Cache Rules: a rule that bypasses the cache for the API except the tracking script's public files. Under When incoming requests match, choose Edit expression and enter:

  Copy Text

  starts_with(http.request.uri.path, "/api/") and not (http.request.uri.path in {"/api/s.js" "/api/r.js"} or starts_with(http.request.uri.path, "/api/c/"))

  Set Cache eligibility to Bypass cache, and place the rule after any other Cache Rule that matches /api/*. Cloudflare caches by file extension, not by content type, and an API URL can end in one (a user id such as someone@example.zip). The API marks every /api answer without a directive of its own private, no-store, which Cloudflare does not cache; the rule still holds under a Cache Rule whose Edge TTL ignores the origin's headers.

• Optionally HTTP/3 for visitors: Speed → Settings → Protocol Optimization.

CheckCopy Anchor Link

https://<your domain>/ is the home page and /login the app, /api/v1/health answers {"data":{"ok":true}}, /api/v1/ready answers 404, and new sessions show visitors' own countries. On the server:

docker compose exec -T api \
  node -e "fetch('http://127.0.0.1:3001/api/v1/ready').then((r) => r.json()).then((j) => console.log(j.data.geoip, j.data.geoFallback))"

prints the MaxMind state and cloudflare.