DanConwayDev
22bbd48537
The production guide was NixOS-only despite presenting itself as the general deployment entry point, and its examples referenced an unavailable GitHub source and a hardening control the module does not set. Turn the entry point into an environment chooser, preserve the corrected NixOS material in its own guide, add a hardened generic systemd unit and repeatable Linux installation, document the preferred unprivileged Proxmox layout, and update repository navigation and architecture references. Each path assumes the shared deployment contract from the container change. Kubernetes automation, remote host mutation, and changes to the existing NixOS module are deliberately excluded. Validated the canonical Git remote with git ls-remote, parsed and scored the systemd unit with systemd-analyze, checked all new deployment-guide links, removed trailing whitespace, scanned the staged diff for key-shaped nsec values, and ran git diff --check.
1.8 KiB
Deploy ngit-grasp
ngit-grasp supports several single-instance production layouts. Choose the guide matching the host you already operate; every guide implements the same deployment contract.
| Environment | Start here | Supplied artifact |
|---|---|---|
| Docker or Podman host | Docker and Compose | Dockerfile, compose.yaml, optional Caddy overlay |
| NixOS | NixOS module | nixosModules.default |
| Debian, Ubuntu, or another systemd Linux | Static binary and systemd | Static flake package and service unit |
| Proxmox LXC or VM | Proxmox | Direct systemd or Compose path |
| Railway, Render, or Fly.io | Managed hosting | Provider configuration templates |
For a fresh internet-facing VPS, the shortest supported path is Docker Compose with the Caddy overlay:
cp deploy.env.example .env
# Set NGIT_DOMAIN in .env and point its DNS records at this server.
docker compose -f compose.yaml -f compose.caddy.yaml up --build -d
scripts/verify-deployment.sh https://ngit.example.com
The Caddy path requires ports 80 and 443. If the host already has a reverse proxy, follow the loopback-only path in the Docker guide instead.
Unsupported layouts
Do not deploy ngit-grasp to serverless functions, an ephemeral filesystem, or multiple replicas. It owns long-lived WebSockets, background synchronization, local Git repositories, LMDB state, and a durable relay identity.
Kubernetes can run the container as a one-replica StatefulSet with a ReadWriteOnce volume, but the repository does not yet ship or promise a Helm chart. A container host or systemd service is simpler unless Kubernetes is an existing operational requirement.