burrow/docs/PLATFORM_SERVICES.md

Platform Services

Burrow's next platform layer is split into service boundaries that can be enabled independently after their security and rollback checks pass.

Identity and KMS

infra/identity owns Google Cloud KMS and Workload Identity Federation resources for the Burrow Google project:

• project id: project-88c23ce9-918a-470a-b33
• project number: 416198671487
• key ring: burrow-identity
• intended keys: Authentik signing, SAML CA signing, release signing

The WIF path is for Authentik-backed Forgejo runners. Runners should exchange an OIDC token for a short-lived Google credential instead of carrying static service-account JSON.

Release storage uses provider-neutral upload wrappers. Garage is the required S3-compatible primary target. GCS is the first backup target and remains the compatibility source for current Sparkle/store follow-on jobs:

• release artifacts: burrow-net-releases
• signed package repositories: burrow-net-packages
• private Nix cache backup: burrow-net-nix-cache

Forgejo jobs authenticate to the same Google project through Authentik-backed WIF, then use gcloud storage for upload/download and Google KMS for release and repository signatures. No rclone transport or Google service-account JSON key is part of the release path.

services.burrow.garage is enabled by the forge host. It provides the host activation point for Garage API, static-web, and admin listeners, and bootstraps the initial single-node layout plus the attic, burrow-releases, and burrow-packages buckets. It creates separate owner/write keys for Attic, release artifacts, and package repositories, plus a read-only backup key for the scheduled Garage-to-GCS mirror.

Garage is now the primary object-storage surface for release/package uploads and the Nix cache. It uses host-local storage for object data and metadata; it does not fan out writes to multiple object-store backends. Multi-cloud failover should be implemented as explicit Garage bucket mirrors/backups, with GCS as the first backup target.

Nix Cache

nix.burrow.net is the Burrow Nix binary cache surface. The forge host runs Attic behind Caddy and stores cache chunks in the Garage attic bucket through Garage's local S3 API. Workers can use https://nix.burrow.net/burrow once the cache public key is published as BURROW_NIX_CACHE_PUBLIC_KEY in Forgejo. The host bootstrap also creates /var/lib/burrow/nix-cache/ci-push-token; seal it as BURROW_NIX_CACHE_PUSH_TOKEN before enabling broad cache publication.

Observability

graphs.burrow.net is backed by Grafana with Authentik SSO. The forge host now imports services.burrow.observability, which starts local Prometheus, OpenTelemetry collector, and Jaeger services. NixOS provisions Grafana datasources; OpenTofu manages checked-in dashboards for the Burrow overview, Headscale, and the broader Prometheus/OpenTelemetry/Jaeger spine.

Jaeger is local-only at first and is queried through Grafana. Headscale metrics are scraped locally. Tailscale SaaS metrics are optional until the OAuth credential file exists.

OpenBao

vault.burrow.net is the planned OpenBao surface. The repository now has:

• infra/openbao for KMS seal wrapping and OpenBao auth/policy resources
• services.burrow.openbao as a disabled-by-default NixOS switch point
• Scripts/openbao-tofu.sh for stack-local OpenTofu operations

OpenBao should not be enabled until the KMS seal key, bootstrap token handling, backup/restore procedure, and Authentik roles are verified.

Jitsi Meet

meet.burrow.net is the planned Jitsi Meet surface. The repository now has services.burrow.jitsi as a disabled-by-default NixOS switch point.

Jitsi is not just an HTTP service. The rollout needs DNS, TLS, XMPP/prosody state, and an explicit UDP media-port decision before activation.

Mail and Webmail

inbox.burrow.net is the intended webmail surface. Stalwart is the planned mail server, but this flake does not currently expose the expected Stalwart NixOS option. Forward Email remains the current production mail path until the Stalwart module name, ports, DKIM rotation, backup target, spam policy, and migration steps are pinned in a follow-up BEP update.

MCP Hub

The MCP hub should be extracted to compatible.systems/burrow/mcp-hub. Until that repository exists, services/mcp-hub/ records the extraction boundary and tool inventory.