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 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.

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:

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:

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.

2.7 KiB Raw Blame History