AI assisted documentation

2026-05-15 04:05:30 +00:00
parent 364ba222e2
commit 6953709574
12 changed files with 2029 additions and 0 deletions
@@ -0,0 +1,53 @@
+# QUptime documentation
+
+Production-oriented documentation for `qu`, a small distributed uptime
+monitor that votes on the health of HTTP/TCP/ICMP targets across a
+cluster of cooperating nodes.
+
+The top-level `README.md` is the marketing pitch and quick-start. The
+pages here go deeper and are organised by what you're trying to do.
+
+## Getting set up
+
+- [Installation](installation.md) — pre-built binaries, building from
+  source, verifying release artifacts, what the install script does.
+- [Configuration](configuration.md) — `node.yaml`, `cluster.yaml`,
+  `trust.yaml`, environment variables, file layout, defaults.
+
+## Running it
+
+- [Architecture](architecture.md) — how nodes form quorum, how a master
+  is elected, how cluster state replicates, what happens during a
+  partition, and exactly which guarantees the design gives you.
+- [Operations](operations.md) — day-2 tasks: upgrades, backups,
+  recovery from a lost node, recovery from a lost quorum, monitoring
+  `qu` itself.
+- [Security](security.md) — the mTLS / TOFU trust model, what the
+  cluster secret protects, how to rotate keys, what to put on a public
+  network and what not to.
+- [Troubleshooting](troubleshooting.md) — common failure modes with
+  the log lines you'll see and the fix.
+
+## Deployment recipes
+
+Pick the one that matches your environment. They share most of the
+operational guidance — what differs is how `qu` is packaged and how
+the inter-node link is secured at the network layer.
+
+- [systemd on bare metal / VM](deployment/systemd.md) — single static
+  binary, hardened unit file, `CAP_NET_RAW` for ICMP.
+- [Docker / docker-compose](deployment/docker.md) — official image,
+  single-node and multi-node compose files, persistent volumes.
+- [Tailscale / WireGuard overlay](deployment/tailscale.md) — nodes in
+  separate networks with no public ingress; cluster traffic stays on
+  the tailnet.
+- [Public-internet exposure](deployment/public-internet.md) — when
+  you have no overlay and `:9901` is reachable from the open
+  internet: firewalling, rate-limiting, secret hygiene.
+
+## A note on stability
+
+The wire protocol (`internal/transport`) and the on-disk format
+(`cluster.yaml`, `node.yaml`, `trust.yaml`) are considered stable
+within a minor version. Breaking changes will bump the major version
+and ship with a migration note.