ADR-0006: Deploy via Docker images on Coolify

Status:  Accepted
Date:    2026-05-02
Owner:   @satya

Context

We need a deploy story that:

Works for both the NestJS backend and the Python workers.
Doesn’t require a full Kubernetes / cloud bill at v0.
Lets a small team push from Git to running prod with one click.
Is easy to rebuild on a different host if the first host disappoints.

Supabase handles its own hosting. Mobile builds go to App Store / Play Store. So the deploy story is really for apps/backend and apps/workers.

Decision

Each backend service ships as a Docker image. Coolify deploys them from this Git repo using each service’s own Dockerfile. Local dev uses infra/docker/docker-compose.yml with the same images.

Environment configuration is per-service via Coolify’s env panel; we ship .env.example files in repo as the source of truth for required variables.

Alternatives considered

Option	Why not
Kubernetes (GKE / EKS)	Massive overhead for v0 traffic; rebuy when we outgrow Coolify.
Vercel / Render	Fine for the API, awkward for headless-browser scrapers and big workers.
Plain VM + systemd	We lose the “git push -> prod” loop and image immutability.
Fly.io	Good alternative; Coolify chosen because we already self-host one VM.

Consequences

Positive

Same image runs locally (docker compose) and in prod.
Rollback is “deploy previous image tag” in Coolify UI.
Docker is portable; Coolify is replaceable.

Negative / risks

Coolify’s reliability is one server; we add an offsite Postgres backup (Supabase handles its own DB) and image-tagging discipline to mitigate.
We’re operating one more piece of infra we didn’t build.

Follow-ups

Add CI to build and push images to a registry on every main merge.
Add health checks and Sentry to both services before any user load.
Document Coolify project / app structure in infra/coolify/README.md.