Self-hosting & backups
Quick deploy
cp apps/api/.env.example apps/api/.env # fill DATABASE_URL, ENCRYPTION_KEY, BETTER_AUTH_SECRETcp apps/front/.env.example apps/front/.envdocker compose up --build- API:
http://localhost:3000— probesGET /healthz(liveness) andGET /readyz(DB + pool). Prometheus scrape atGET /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=trueso rate-limit sees the real IP (cf-connecting-ip/x-real-ip). Withfalse, 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_restoreto 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.
docker compose -f docker-compose.uploader.yml up -d# open http://<host>:8080 → save credentials → Get code → approve at levelcast.org/linkFastest 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.