Feat/improve env bootstraping

[bartrosa]

Summary

This PR turns homelab-cli from a provisioning-focused tool (v0.2) into a full developer environment platform: installable stack components, compose-backed local services, and graph databases for GraphRAG workloads — all from one binary.

Branch: feat/improve-env-bootstraping
Scope: 39 commits · 107 files · +6,691 / −267 lines
Baseline preserved: lab iso, lab bootstrap essentials, self-update, install script — no regressions on v0.1/v0.2 flows.

After merge, a typical fresh-machine workflow looks like:

lab bootstrap essentials --yes
lab stack install --preset backend --yes
lab services up --preset graphrag --yes
lab services connect arcadedb

---

What's new

lab stack (rename from lab toolchain)

• lab stack replaces lab toolchain with aliases toolchain and tc (backward compatible).
• Component registry with dependency-ordered install, dry-run planning, and skip-if-installed behavior.
• 26 installable components across 7 categories: languages (Python, Go, Rust, Scala, Kotlin, …), build tools, containers, GPU stacks (CUDA/ROCm), VCS, package managers, embedded DBs (SQLite, DuckDB).
• Stack presets: minimal, basic, backend, frontend, systems, jvm, ml, data, gpu-nvidia, gpu-amd, full.
• Shell PATH management via idempotent managed blocks in ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish.
• GPU detection (lab stack gpu) from lspci output.

lab services framework

Replaces the v0.1 stub with a full compose orchestrator:

• Service interface, config schema, stdin prompt engine (golang.org/x/term — only new dependency).
• Shared Docker/Podman network homelab-net, embedded templates, secret handling, .env chmod 600.
• Runtime auto-detection: Docker on Ubuntu, Podman on Silverblue.
• Commands: init, up, down, restart, status, connect, logs, rm, preset list/show.

17 compose-backed services

Category	Services
database	postgres, mysql, mongodb, clickhouse
cache	redis, valkey
message-queue	rabbitmq, nats
vector	qdrant, weaviate
observability	prometheus, grafana, loki, tempo
storage	minio
graph	arcadedb, nebulagraph

Postgres supports plugin combinations (pgvector, postgis, timescaledb) via embedded Dockerfile when 2+ plugins are selected.

Grafana auto-provisions datasources (prometheus, loki, tempo, postgres, clickhouse) with soft-fail if a target is down.

Graph databases (Apache 2.0)

Two sovereign-friendly graph engines, selected after a 2026 license review (Neo4j GPLv3, FalkorDB SSPL, Memgraph/ArangoDB BSL excluded):

Service	Description
arcadedb	Single-container multi-model DB (graph, document, KV, vector). Studio UI, Cypher/Gremlin/SQL, optional MongoDB/Redis protocol plugins.
nebulagraph	4-container distributed stack (metad + storaged + graphd + studio). nGQL (openCypher-compatible). Automated post-init for storage host registration and root password rotation.

New presets:

• graphrag — arcadedb + qdrant + minio + postgres (multi-modal AI stack)
• graph-lab — arcadedb + nebulagraph (side-by-side comparison, no port collision)

New service category: graph (lab services list --category graph).

Optional PostUpper interface — NebulaGraph runs post-init after compose up without breaking existing services.

High-level wrappers

• lab obs up/down → observability preset
• lab vector up <id> → forwards to lab services up (qdrant, weaviate, arcadedb, nebulagraph)
• lab data up <id> → postgres, clickhouse, minio

Configuration

Extended ~/.config/homelab-cli/config.yaml:

stack:
  default_preset: backend
  presets:
    my-workflow: [python, node, go, docker]
  components:
    python: { version: "3.12" }

services:
  runtime: auto
  network: homelab-net
  instances:
    postgres:
      plugins: [pgvector, postgis]
      password: env:LAB_POSTGRES_PASSWORD
  presets:
    my-ml-lab: [postgres, qdrant, minio, clickhouse]

Breaking default: services.runtime changed from podman → auto.

---

Documentation

• README.md — dev environment + services walkthrough
• docs/commands.md — full lab stack and lab services reference
• docs/configuration.md — stack: and services: sections
• docs/services.md — catalog of all 17 services, graph licensing rationale, embedded graph alternatives (Kuzu/LadybugDB)
• CHANGELOG.md — v0.3 Developer Environment + Graph Databases entries

---

Design decisions

1. Postgres multi-plugin — embedded Dockerfile + compose build on up when 2+ plugins are selected (no single upstream image covers all combinations).
2. Grafana datasource provisioning — soft-fail; user restarts Grafana after bringing up missing backends.
3. Pinned image versions in all templates; override via --set version=….
4. ArcadeDB MCP plugin — gated on 24.11.x; warning logged if enabled on unverified versions. TODO: confirm plugin in official image.
5. NebulaGraph post-init — shell-side idempotency via SHOW HOSTS + password probing (no marker files).
6. NebulaGraph auth — enable_auth=true by default; post-init rotates root/nebula → random .env password.
7. lab vector up arcadedb — forwards without blocking; connect notes that ArcadeDB is multi-model, not a dedicated vector DB.
8. No Ruby, no .NET, no Faiss as stack components — by design.

---

Test plan

• make ci green (fmt, vet, lint, test, build)
• lab stack list — 26+ components in 7 categories
• lab stack install --preset ml --yes — installs without errors
• lab stack path refresh — idempotent shell rc block
• lab toolchain install python --yes — alias works
• lab services list — 17 services with status
• lab services init postgres --set plugins=pgvector,postgis --yes — generates compose + Dockerfile + .env (600)
• lab services up --preset observability --yes — prometheus, loki, tempo, grafana healthy
• lab services init arcadedb --set databases=knowledge_graph --yes && lab services up arcadedb
• curl http://127.0.0.1:2480/api/v1/ready → 200
• lab services connect arcadedb — full endpoint list
• lab services init nebulagraph --yes && lab services up nebulagraph — 4 containers healthy, post-init registers storaged0
• lab services up --preset graphrag --yes — all 4 services up
• lab services up --preset graph-lab --yes — both graph DBs parallel, no port conflict
• lab vector up arcadedb — wrapper forwards correctly
• lab obs up — observability preset
• Regression: lab bootstrap essentials --dry-run, lab iso list, lab self-update --check

---

Migration notes

Before	After
lab toolchain install go	lab stack install go (alias still works)
services.runtime: podman	services.runtime: auto (explicit override still supported)
lab services ensure ml-stack	Still works (legacy homelab-repo compose)

---

Out of scope (follow-up PRs)

• NebulaGraph multi-node scale-out (--nodes 3)
• JanusGraph / HugeGraph
• Embedded graph in lab stack (LadybugDB/bighorn when stable)
• Full lab services logs compose integration (partial stub remains)
• Integration tests in CI (make test-integration target added, not run in default CI)