Skip to content
oboroxyzPublic

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

haco.sh

CI

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.


What it does

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 bootstrap for fresh installs (no browser needed), haco init --from-backup for 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).


Repository layout

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.


Install (development)

pnpm install
pnpm --filter @haco-sh/web dev          # http://localhost:5173
pnpm --filter @haco-sh/cli haco --help

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


CLI reference

Lifecycle

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.

Operations

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.

Backup

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

Updates

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.

Infra

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


Architecture decisions

  • State vs config separation. data/ is per-service backed up. haco.config.yml + .env form 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. See packages/core/src/backup.ts.
  • Pure builders + side-effect runners. packages/core contains string-in/string-out functions (generateCompose, buildBackupPlan, assessSmoke, …). The CLI's shell.ts is the only place subprocesses are spawned. Tests live with the builders, not the executors.
  • Lock-based updates with auto-rollback. haco.lock.yml pins image:tag@sha256:digest per container. haco update walks pre-backup → pull → write lock → regen compose → up -d → smoke (poll Health.Status) → revert on fail. The previous lock is always kept as haco.lock.yml.prev.
  • Backup hooks declared per service. SERVICE_BACKUPS in services.ts ships pre/post commands (docker compose stop X for stateful, sqlite .backup later, forgejo dump later). The CLI runs them as a try { 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-backup extracts to a sandbox and strips that prefix so the new VPS doesn't need the same path layout.

Status

Working (with unit tests):

  • Web wizard generates the full file set including haco.config.yml.
  • haco bootstrap and haco init --from-backup produce equivalent output.
  • haco backup → haco restore latest <svc> --force round-trips data byte-for-byte (verified by scripts/e2e.sh).
  • haco update [container] with auto-rollback on smoke failure.
  • haco doctor flags missing deps, port collisions, bad permissions.

Not yet:

  • Single-binary distribution. Today: pnpm install from 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 bootstrap prompts (currently flag-driven only).

License

MIT.

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages