Self-sovereign stack for individuals, families, and communities — ten open-source services on a single €4/month VPS, generated from a wizard, managed by a CLI, with first-class backup / update / DR.
Status: pre-alpha. Code is feature-complete but unverified against a live VPS. See Status below.
Pick services (mail, chat, files, passwords, identity, git, DNS, AI, …) and haco emits a complete deployable stack: docker-compose.yml, Caddyfile, .env, DNS setup script, healthcheck probes, restic backup hooks, and a portable haco.config.yml describing the choice. Two entry points:
- Web wizard at
/build— browse services, watch a live RAM meter, download the bundle. - CLI —
haco bootstrapfor fresh installs (no browser needed),haco init --from-backupfor disaster recovery on a new VPS.
After install, the CLI handles the operational lifecycle: snapshot, restore, update with auto-rollback, status, doctor, and docker compose wrappers (logs, shell, restart, stop, start).
haco-sh/
├── apps/
│ ├── web/ React wizard (TanStack Router + Tailwind v4)
│ └── cli/ haco command (Node + commander + tsx)
├── packages/
│ └── core/ @haco-sh/core — pure data + generators
│ └── src/
│ ├── services.ts SERVICES + CATEGORIES + SERVICE_BACKUPS
│ ├── images.ts SERVICE_IMAGES + container→service mapping
│ ├── containers.ts enabledContainers (mirrors compose generator)
│ ├── generators.ts compose / Caddyfile / env / dns / blocky / localhost-test
│ ├── config.ts haco.config.yml (de)serializer + generator
│ ├── lock.ts haco.lock.yml schema + diff
│ ├── backup.ts restic plan builders (pure)
│ ├── cron.ts systemd unit generators
│ ├── smoke.ts assessSmoke for healthcheck verdicts
│ └── palette.ts shared color tokens (web + UI)
├── scripts/
│ └── e2e.sh backup → restore roundtrip against real Docker
└── pnpm-workspace.yaml
The split is intentional: packages/core is pure (no React, no I/O), so the same generators back both the web wizard and the CLI. apps/* are leaf consumers.
pnpm install
pnpm --filter @haco-sh/web dev # http://localhost:5173
pnpm --filter @haco-sh/cli haco --helppnpm test runs core unit tests (84 across generators / lock / config / cron / containers / smoke).
pnpm -r typecheck typechecks all packages.
pnpm e2e runs the integration test (requires docker daemon and restic on PATH).
| Command | Purpose |
|---|---|
haco bootstrap --domain X --services A,B,C |
Generate a fresh install from flags (no wizard needed). |
haco init --from-backup <repo> |
Disaster recovery: pull envelope snapshot, regenerate stack files, restore per-service data. |
| Command | Purpose |
|---|---|
haco status |
Containers + state + lock alignment + last snapshot, in one table. |
haco doctor |
Prereq checks: docker, restic, disk, config validity, .env perms, host port collisions. |
haco logs [services...] |
docker compose logs (-f, --tail). |
haco shell <service> [cmd...] |
docker compose exec <s> sh -c "...". |
haco restart / stop / start [services...] |
Pass-through to docker compose. |
| Command | Purpose |
|---|---|
haco backup [services...] |
Per-service snapshot via docker compose stop → restic backup → start. Always appends an envelope snapshot (haco.config.yml + .env) so DR has a starting point. |
haco snapshots |
List restic snapshots tagged haco. |
haco verify |
restic check. |
haco prune |
Apply retention (default 7d / 4w / 12m / 5y). |
haco restore <snap|latest> [services...] |
In-place (--force) or alternate target (--to). |
| Command | Purpose |
|---|---|
haco update check |
Compare haco.lock.yml digests with registry. |
haco update [containers...] [--all] |
Auto-backup → docker pull → write new lock → regenerate compose → up -d → smoke check (HEALTHCHECK-aware) → on failure: revert lock + restart with previous digest. |
haco rollback [containers...] |
Restore haco.lock.yml.prev and recreate. |
| Command | Purpose |
|---|---|
haco install-cron |
Generate four systemd units (backup + verify, service + timer) under ./systemd-units/ plus install instructions. |
All install-aware commands accept --install-dir. All backup/restore commands honor RESTIC_REPOSITORY / RESTIC_PASSWORD (or --repo).
- State vs config separation.
data/is per-service backed up.haco.config.yml+.envform an envelope snapshot. Everything else (docker-compose.yml,Caddyfile, …) is generated from those two and never backed up — DR regenerates them with the latest core. Seepackages/core/src/backup.ts. - Pure builders + side-effect runners.
packages/corecontains string-in/string-out functions (generateCompose,buildBackupPlan,assessSmoke, …). The CLI'sshell.tsis the only place subprocesses are spawned. Tests live with the builders, not the executors. - Lock-based updates with auto-rollback.
haco.lock.ymlpinsimage:tag@sha256:digestper container.haco updatewalkspre-backup → pull → write lock → regen compose → up -d → smoke (poll Health.Status) → revert on fail. The previous lock is always kept ashaco.lock.yml.prev. - Backup hooks declared per service.
SERVICE_BACKUPSinservices.tsships pre/post commands (docker compose stop Xfor stateful, sqlite.backuplater,forgejo dumplater). The CLI runs them as atry { snapshot } finally { post }so a failed restic call doesn't leave the service stopped. - DR convention. The envelope snapshot's restic paths reveal the source install dir.
haco init --from-backupextracts to a sandbox and strips that prefix so the new VPS doesn't need the same path layout.
Working (with unit tests):
- Web wizard generates the full file set including
haco.config.yml. haco bootstrapandhaco init --from-backupproduce equivalent output.haco backup → haco restore latest <svc> --forceround-trips data byte-for-byte (verified byscripts/e2e.sh).haco update [container]with auto-rollback on smoke failure.haco doctorflags missing deps, port collisions, bad permissions.
Not yet:
- Single-binary distribution. Today:
pnpm installfrom source. Goal:curl -fsSL haco.sh/install | bash. - Validated against a real VPS with real DNS / ACME / mail deliverability.
- HEALTHCHECK probes for
stalwart,tuwunel,ollama,soft-serve(image tooling unconfirmed). - Interactive
haco bootstrapprompts (currently flag-driven only).
MIT.