Skip to content

Self-hosting & backups

Quick deploy

Terminal window
cp apps/api/.env.example apps/api/.env # fill DATABASE_URL, ENCRYPTION_KEY, BETTER_AUTH_SECRET
cp apps/front/.env.example apps/front/.env
docker compose up --build
  • API: http://localhost:3000 — probes GET /healthz (liveness) and GET /readyz (DB + pool). Prometheus scrape at GET /metrics.
  • Front: http://localhost:4321. PUBLIC_* vars are build-time (Astro inlines them) — changing the URL requires a rebuild.
  • Behind a proxy (Coolify/Cloudflare): set TRUST_PROXY=true so rate-limit sees the real IP (cf-connecting-ip / x-real-ip). With false, limiting is skipped with a loud warning.

Coolify (production)

Coolify builds the three Dockerfiles (api, front, docs) from this repo.

Required env (Coolify project env, never in git): ENCRYPTION_KEY, BETTER_AUTH_SECRET, DATABASE_URL, ADMIN_EMAILS, STRIPE_*, SHARED_LINK_SECRET, FRAME_PAIRING_SECRET, FIREBASE_SERVICE_ACCOUNT_JSON.

Backups (Coolify + R2)

  • Coolify scheduled backup → pg_dump → Cloudflare R2 (offsite, versioned).
  • RPO/RTO = the Coolify schedule (recommended: daily, retain 7).
  • Excluded: valkey-data (cache).
  • Restore test: quarterly pg_restore to staging + GET /readyz → ready.

Health data note: if you self-host, you are responsible for TLS, backups, access control and the privacy regulations of your jurisdiction (GDPR Art. 9 for glucose data). See Data Retention.

Uploader: keep your provider passwords at home

Don’t want to give levelcast.org your LibreLinkUp/Dexcom password? Run the lightweight uploader on your own box (Raspberry Pi, NAS, VPS). It polls providers locally and links to your levelcast.org account via device flow — you approve a short code at /link while logged in. The box never asks for your levelcast password, and the server never sees provider passwords.

Terminal window
docker compose -f docker-compose.uploader.yml up -d
# open http://<host>:8080 → save credentials → Get code → approve at levelcast.org/link

Fastest zero-click path: in levelcast.org go to Connections → “Run your own uploader”, pick the patient and mode, and run the generated docker run -e BOOTSTRAP_TOKEN=… command. The box claims the one-shot token on boot (10-min TTL, single-use, rotated on regenerate) and links itself — the modal shows it live when detected. For encrypted mode, paste the vault key shown on the box (:8080) into the modal afterwards.

Two link modes:

  • Direct — the box uploads normalized readings; the cloud stores them (alerts, rules and reports work as usual).
  • Encrypted (E2E) — the box uploads opaque AES-GCM envelopes; the cloud is a blind viewer. The vault key (DEK) travels only inside the pairing QR and lives in your browser storage. Lose it = history is unrecoverable.

Switching to Encrypted needs no manual key paste on boxes v0.5.0+: open the box :8080 page, generate a one-time 6-digit pairing code and type it in Connections → Manage. Browser and box then run an SRP-6a PAKE over the untrusted relay — the DEK transfers itself sealed, the cloud can neither read nor substitute it, and wrong codes just burn online attempts (5 per code, then it locks). Fully automatic transfer without the code would be silently MITM-able by the relay, so the short code stays: it is the only human-authenticated step, and the only secret that never touches the cloud.

Patients are managed on levelcast.org (canonical). The box only maps source → patient after linking, and works standalone (local mini-UI) with no account at all.

Remote management

The box phones home: every poll cycle it sends a heartbeat (status, usernames, queue depth — never passwords) and picks up queued commands. Boxes on v0.4.0+ also hold an outbound WebSocket (NAT-friendly, LINK_TOKEN in the first message, never in the URL): commands then arrive instantly via a commands-pending wake-up instead of waiting for the next heartbeat, and the box reads as Live in the table. The queue stays the guarantee — offline or older boxes simply pick commands up on their next poll. From Connections → Self-hosted uploaders → Manage you can remotely: pause/resume each source, change the poll interval, trigger a poll, switch link mode (direct ↔ encrypted; the vault key ceremony for E2E still happens with the key shown on the box), set provider logins as sealed envelopes (RSA-OAEP-256+GCM-v1, encrypted in your browser with the box key — the cloud only forwards ciphertext and never sees passwords; identical in direct and encrypted modes), and unlink. Direct entry on the box itself (:8080) stays available.