Self-hosting overview

PilotFox runs one way, the way pilotfox.app runs:

• Your server runs docker-compose.yml from the root of this repository: the API, Postgres 17 with its continuous backups, ClickHouse, Valkey and cloudflared. It publishes no port.
• Cloudflare serves the web app and the public site from a Worker, and sends the API's paths to your server through a Cloudflare Tunnel.

The only image built is the API's (backend/apps/api/Dockerfile), on the server from a checkout of this repository (no release images are published yet); the others are pulled. Every command in these pages runs from the repository root. The operator guide in the repository, backend/docs/deploy.md, has the reasoning and test notes behind these procedures.

A self-hosted instance runs the same API, web app and tracking script as the rest of these docs describe. Wherever an example uses https://pilotfox.app, use your instance's PUBLIC_URL instead.

What runs whereCopy Anchor Link

                visitors (HTTPS, HTTP/3)
                          │
               ┌──────────▼───────────┐
               │   Cloudflare's edge  │  /api/*, /.well-known/*, /maps/*  → the tunnel
               │                      │  every other path                 → the web app's Worker
               └──────────┬───────────┘
                          │  tunnel (outbound from the server, 7844/tcp+udp)
   your server ┌──────────▼───────────┐
               │     cloudflared      │  network "tunnel" (cloudflared is 10.89.242.2)
               └──────────┬───────────┘
               ┌──────────▼───────────┐
               │         api          │  REST API, tracker, ingest, jobs, MCP
               └──┬────────┬────────┬─┘
                  │        │        │      network "stores"
         ┌────────▼──┐ ┌───▼──────┐ ┌▼─────────┐
         │ postgres  │ │clickhouse│ │  valkey  │
         └────┬──────┘ └──────────┘ └──────────┘
              │ socket
         ┌────▼──────┐
         │ pgbackrest│  base backups; postgres archives its WAL ──► R2 (network "postgres-egress")
         └───────────┘

The compose project is mine-analytics. Six networks keep the services apart:

• app: the API's route out (MaxMind, R2, mail, payment providers).
• stores: the API, Postgres, ClickHouse and Valkey. It is internal, with no route out.
• clickhouse-egress: ClickHouse alone, so it can write its backups to R2.
• postgres-egress: Postgres and pgbackrest, so they can write Postgres's backups to R2.
• tunnel: cloudflared and the API, internal. cloudflared has the fixed address 10.89.242.2, the only peer whose forwarding headers the API believes (TRUST_PROXY). TUNNEL_NET_PREFIX moves the subnet.
• tunnel-egress: cloudflared alone, its route to Cloudflare.

Optional services extend what the instance does: Cloudflare Email Sending (or an SMTP server) for mail, a MaxMind account for visitor locations, a Cloudflare R2 bucket for session replay, imports and backups (Postgres's continuous ones included), and a Google Cloud OAuth client for Search Console. See Requirements.

What is exposedCopy Anchor Link

No service publishes a port, and the server needs no inbound port at all. Everything reaches it through the tunnel, which serves only the routes of your own Cloudflare account.

The /docs/* pages are the public site's user guides. This developer documentation is a separate static site, built from pilotfox-documentation/ (bun run build writes out/) and served by a Worker of its own on a host name of its own (pilotfox.app's is docs.pilotfox.app). Every instance serves its own API reference at /api/docs/ and the OpenAPI document at /api/docs/openapi.json.

• Headers. The API sends its own security headers. For the web app the Worker sends Content-Security-Policy: frame-ancestors 'none', X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin and Strict-Transport-Security: max-age=31536000; includeSubDomains.
• No visitor addresses or tokens in logs. The API's request log keeps no visitor address and no URL values (share tokens travel in URLs); cloudflared logs requests only at its debug level, which is off; the Worker has Workers Logs off.
• Compression. Cloudflare compresses responses for visitors; the live event stream is passed on event by event.

For administration, open the stores through compose: docker compose exec postgres psql -U app -d app, docker compose exec clickhouse clickhouse-client and docker compose exec valkey valkey-cli, which need no password typed (Postgres trusts its own socket; the others find theirs in the container's environment).

Next stepsCopy Anchor Link