chore: scaffold M0 — repo structure, ADRs, dev environment, pre-merge checklist

2026-08-02 10:26:49 +02:00
commit 581191e93a
20 changed files with 781 additions and 0 deletions
@@ -0,0 +1,68 @@
+# Homelab Copilot
+
+An AI-powered platform that understands your homelab: infrastructure, documentation, Docker stacks, and network — eventually capable of monitoring, troubleshooting, and safely automating tasks.
+
+**Status:** Milestone M0 — Foundation. No application code yet. This milestone is scaffolding and decisions only.
+
+See [`docs/architecture/00-founding-strategy.md`](docs/architecture/00-founding-strategy.md) for the full founding strategy, architecture, roadmap, and milestone plan.
+
+## Current milestone: M0 — Foundation
+
+Goals, acceptance criteria, and required technologies are defined in the founding strategy doc, Section 8. In short: repository scaffold, core technology decisions recorded as ADRs, local dev environment, and a manual pre-merge checklist (CI is intentionally deferred — see ADR-003).
+
+## Running locally
+
+The M0 dev environment brings up the platform's own supporting services (Postgres, Qdrant, Redis) — no application backend exists yet.
+
+```bash
+cp .env.example .env
+# edit .env and set a real POSTGRES_PASSWORD
+
+docker compose \
+  -f infrastructure/docker/docker-compose.yml \
+  -f infrastructure/docker/docker-compose.dev.yml \
+  up -d
+```
+
+Check that everything came up:
+
+```bash
+docker compose \
+  -f infrastructure/docker/docker-compose.yml \
+  -f infrastructure/docker/docker-compose.dev.yml \
+  ps
+```
+
+- Postgres → `localhost:5432`
+- Qdrant → `localhost:6333` (HTTP), `localhost:6334` (gRPC)
+- Redis → `localhost:6379`
+
+To tear down:
+
+```bash
+docker compose \
+  -f infrastructure/docker/docker-compose.yml \
+  -f infrastructure/docker/docker-compose.dev.yml \
+  down
+```
+
+## Documentation map
+
+| Doc | Purpose |
+|---|---|
+| `docs/architecture/00-founding-strategy.md` | Full vision, architecture, roadmap, milestone plan |
+| `docs/architecture/adr/` | Architecture Decision Records |
+| `docs/architecture/pre-merge-checklist.md` | Manual checklist run before every merge to `main` (replaces CI for now) |
+| `docs/roadmap/roadmap.md` | Living roadmap, MVP → v3.0 |
+| `docs/deployment/deployment-topology.md` | Which branch deploys where, and how (Coolify) |
+
+## Deployment
+
+Not yet connected. `main` will eventually be deployed by Coolify via a Gitea webhook — see ADR-003 and `docs/deployment/deployment-topology.md`. `infrastructure/docker/docker-compose.prod.yml` is scaffolded now so the repo is ready for that, but nothing is wired up yet.
+
+## Contributing (to yourself, in six months)
+
+- Trunk-based: short-lived feature branches off `main`, no long-running `develop`.
+- Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`).
+- Every PR: run through `docs/architecture/pre-merge-checklist.md` before merging.
+- Docs updated in the same PR as the code they describe — never a follow-up task.