Self-host Zuppo (alpha)
One binary serves git over HTTP and SSH, the API and the embedded UI. It also needs the pinned C git; Zoekt is optional.
One binary serves git over HTTP and SSH, the API and the embedded UI. It also needs the pinned C git; Zoekt is optional. This is an alpha source install, not a promise of published binaries, signed images, a chart registry or a production SLA. See operations, the API and the agent quick-start.
Build and start a solo instance
From the repository root, with the Rust toolchain in rust-toolchain.toml, Node/npm and git:
VITE_ZUPPO_SITE=off scripts/web.sh build
cargo build --profile release-selfhost --locked -p zuppo -p zuppo-axi
export PATH="$PWD/target/release-selfhost:$PATH"VITE_ZUPPO_SITE=off leaves out the zuppo.dev homepage and marketing pages: / opens the app, and the docs stay. Use CARGO_TARGET_DIR instead of target in PATH if you set it. Use the git produced by bench/spikes/spk4-git-transport (currently ~/.cache/zuppo-tools/git-2.56.0/bin/git), not an old system git without reftable support. zuppo serve --help lists all flags and environment variables; it is the authority for the installed version.
The server binaries (zuppo, zuppo-apid, zuppo-gitd, zuppo-gitd-receive, zuppo-searchd, zuppo-mountd) allocate with mimalloc, their default mimalloc feature; cargo build --no-default-features -p <binary> builds one with the system allocator instead.
For a fresh local evaluation, choose an empty state directory on local disk:
export ZUPPO_STATE="$HOME/.local/share/zuppo" export ZUPPO_HOST=http://localhost:8080 export ZUPPO_HEALTH_URL=http://127.0.0.1:8080/healthz zuppo serve --state "$ZUPPO_STATE" --listen 127.0.0.1:8080 --origin "$ZUPPO_HOST" --no-ssh
Leave that process running and use a second terminal for the following blocks. They assume a fresh instance, zuppo, zuppo-axi, curl and jq on PATH, and the three variables above exported. The documentation smoke runner supplies its own isolated server, temporary state and free port. Fences marked sh runnable run in order in that runner; other fences need the stated deployment or build prerequisites and are not run by the fast smoke. The health CLI uses a literal IPv4 address because a localhost lookup can prefer IPv6 while this example binds IPv4 only; the browser origin remains localhost for people sign-in.
zuppo version zuppo health --url "$ZUPPO_HEALTH_URL" zuppo admin --state "$ZUPPO_STATE" status | jq -e '.uptime_s >= 0' zuppo admin --state "$ZUPPO_STATE" org-create acme --name Acme --jurisdiction eu DOC_PERSON=$(zuppo admin --state "$ZUPPO_STATE" person-add alice --email alice@example.com | jq -er '.person') export DOC_PERSON zuppo admin --state "$ZUPPO_STATE" member-set acme "$DOC_PERSON" owner zuppo admin --state "$ZUPPO_STATE" login-link "$DOC_PERSON" | jq -e '.url | startswith("http")'
The link is a secret valid for 15 minutes; send it privately. Sign in and register a passkey. eu or us is mandatory and immutable for an org. An origin is also recorded at first start: changing it later is refused, because grants and repository locations name it.
Expose it safely
Use a dedicated OS account; state is created mode 0700 and admin.sock mode 0600. Restrict backup and bootstrap token files to that account. Do not expose the admin socket or gitd's internal port. For other users, set an HTTPS origin and put a TLS proxy in front of the loopback listener, or supply --tls-cert and --tls-key to serve TLS directly. Only HTTPS or http://localhost supports people sign-in/passkeys; another plain HTTP origin gives sign-in 503. Lift proxy body/time limits for git transfers. --http3 needs TLS and UDP on the same port; stock git still uses TCP.
SSH is on --ssh-listen (default 2222); register an ed25519/ECDSA public key with zuppo admin ssh-key-add, or let people add their own under Settings → Account (a git-only grant in an org they are a member of; /auth/ssh-keys). Distribute its host fingerprint out of band. Removing a registered key revokes its grant. Use --no-ssh if only HTTPS is needed. Spectrum bridging is a separate deployment, not required for self-host.
Email codes (6-digit sign-in, sign-up unless --no-signup, adding addresses) need a mail sender: --mail smtps://USER@HOST (or smtp://…:587 with STARTTLS) with the password in ZUPPO_MAIL_PASSWORD, and --mail-from 'Zuppo <no-reply@example.org>'. --mail file:///DIR writes each mail to DIR instead, for a trial. Without --mail the sign-in page has no email form.
Run under your service manager with SIGTERM and at least 30 seconds of shutdown grace. Do not start a second writer: solo takes an exclusive state lock and refuses network filesystems (NFS/SMB/CephFS/FUSE included). A network-mounted SQLite directory is not an HA profile.
Team: Postgres and S3
Use the same binary with --postgres and --s3-bucket. Metadata, refs, people, SSH keys and host identity are in Postgres; packs/build-cache objects are in the bucket; --state holds rebuildable caches and the admin socket. One writer per database is enforced by an advisory lock; losing that lock connection stops the process. This is replacement, not active/active HA.
The Compose guide supplies the exact environment file, bootstrap, credentials, image build and restore procedure. On this development Mac Docker uses Colima (colima context), not Docker Desktop. In production use a private network: the current Postgres adapter does not support TLS. S3 credentials are AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY; endpoint/region are explicit for non-AWS stores. The bucket must honour create-only If-None-Match: * writes. Garage v2.5 does not; the local stack uses MinIO instead. Never use a public plaintext Postgres connection as a workaround for its TLS limitation.
Kubernetes
Helm installation and values are the canonical chart instructions. The chart in deploy/helm/zuppo runs one replica with Recreate, non-root uid 65532, read-only root filesystem and /healthz probes. Solo needs a local-block PVC (retained on uninstall); team needs external Postgres/S3 and may discard its cache volume. It does not create production database/object-store services. Set origin, image repository and managed Secrets before installation. There is no published default image to pull. Secret checksums roll the pod when chart-owned credentials rotate; arrange a rollout yourself for externally managed Secrets.
Upgrades and LTS
Read release policy before replacing a binary/image. Record zuppo version, state format and backups first. Stop the old process, replace the binary, start on the same state and origin, then check health, a representative API read and git clone. Patches have no schema change; minors may migrate forward. A newer version stamp alone can refuse an older binary even when the schema is unchanged: rollback means restore a matching backup, not run an old image over the new state. Cross each major in sequence. Helm rollback is safe for configuration, not a guarantee of image downgrade. Monthly minors, one yearly LTS and about 15 months of security-only LTS fixes are the policy; a 7-day RC soak and two weeks of cloud parity remain release gates, not claims that an alpha build has passed them.
Backup, restore and disaster recovery
- Solo: quiesce writes by stopping the process, then copy/snapshot the whole state directory, including every SQLite/WAL file, objects, people, SSH host key and version/origin stamp. A live copy of just
api.sqlite3is not a consistent backup. Keep mode/ownership and encrypt off-host copies; they contain refresh tokens and signing/key material. Restart only after the copy ends. - Team: stop the writer/compactor; dump Postgres first, then copy the bucket, as in the Compose backup recipe. Preserve database, bucket and key backups as one recovery set. The cache volume alone is not a backup.
- Restore into a separate empty state/database/bucket with the matching version and original origin. Keep the old writer stopped; verify health, API records, SSH identity and a fresh clone before routing traffic. Test this periodically; a backup without a successful restore is not proof.
- Cloud outage: the read-only standby runbook describes the independent DR host, one store per jurisdiction, promotion, DNS and failback. Promotion never enables writes. Only refs backed by copied packs are served. Changes/reviews/members are not recovered by this standby: metadata export DEP-B3 is not built. It is not a full solo/team backup replacement.
Capacity: measurements, not guarantees
Historical HOST-1 measurements on arm64/macOS and an aarch64-musl Docker build (2026-11-11), not a dedicated production VM or a fresh measurement of this alpha head:
| Item | Measured | Qualification |
|---|---|---|
| Static stripped binary | 45.9 MB | excludes git/Zoekt; release-selfhost |
| Idle RSS | 25.5 MB | 60 seconds, not the required 24-hour soak |
| Small-team peak RSS | 486.6 MB | includes git children; 10 clients, 5 repos, 300 seconds |
| Warm cold-start maximum | 0.086 s | exec to first health 200, 40 runs |
| Solo restart downtime maximum | 0.76 s | five windows, not an upgrade guarantee |
The small-team run raised the person-hour budget to 100,000; the shipped 5,000-point budget throttles a fast client sooner. Plan a 4 vCPU / 16 GB / NVMe solo VM as the plan's starting profile, not a measured minimum. Provision for repository/cache/compaction scratch plus backup headroom; RSS alone does not size disk or CPU. Re-measure with scripts/selfhost-footprint.sh and scripts/team-pc28.sh on your target hardware. Team's historical patch downtime was measured on a Mac VM, not your Linux host. See load caveats.