homelab-copilot/docs/architecture/adr/003-deployment-strategy.md

ADR-003: Deployment strategy

Status: Accepted Date: 2026-08-02

Context

We need a way to get merged code running on real infrastructure. Options considered: a Gitea Actions CI/CD pipeline, a fully manual deploy process, or a dedicated deployment platform. The project owner already runs (or intends to run) Coolify in the homelab, and wants it as the long-term deployment mechanism: Coolify connects to Gitea via webhook, and automatically pulls, builds, and deploys on merge to the appropriate branch.

Building a full CI pipeline (lint, test, build, deploy stages) now, before there is any application code to test, would be effort spent on tooling with nothing yet to validate — directly against the founding strategy's core principle of avoiding infinite runway to real value (Section 1.1).

Decision

• Gitea remains the Git source of truth. All code, config, and IaC live there.
• Coolify handles build and deployment, triggered by a webhook on merge to main.
• CI is intentionally deferred. For M0 and M1, a manual pre-merge checklist (docs/architecture/pre-merge-checklist.md) substitutes for automated checks. This is a conscious tradeoff, not an oversight — revisit once there's a real test suite worth automating.
• No staging branch/environment yet. Given the MVP is read-only (Section 1.5), the blast radius of a bad production deploy is low. Revisit at v0.5, when the Execution Guard starts allowing real write actions against homelab infrastructure (founding strategy, Section 7).
• The repository is structured to be Coolify-ready from day one (separate docker-compose.prod.yml, docs/deployment/) even though the actual Coolify connection is not made in M0 — there's nothing deployable yet.

Consequences

• Merges to main will, once Coolify is connected, deploy directly to production with no automated gate in between — raises the real stakes of the manual pre-merge checklist; it needs to be used honestly, not treated as a formality.
• We save the time cost of building and maintaining a CI pipeline before there's anything meaningful to run through it.
• We accept slower feedback on regressions until CI is eventually introduced (tracked as a backlog item once a real test suite exists — see roadmap).
• The Coolify connection itself (webhook setup, environment variables) is deliberately out of scope for M0 — it becomes real at the end of M1, once main contains a working service worth deploying.