Maintainer guide

This guide is for maintainers of the Fediversity code. It tells how to check a change without deploying, how to deploy from CI and from a workstation, how to update nixpkgs, and where to find the logs. Each step links to the notes that give more detail:

• notes/bootstrap.md -- setting up Fediversity for a hosting provider.
• notes/cd-credentials.md -- the deploy coordinates, and how CI uses them.
• notes/private-access.md -- how to reach the admin surface.
• notes/forward-recovery.md -- how to recover a failed apply, and what a new TF resource must do to fit.

The flake attributes page tells how the attributes below get their names. To add an application that operators deploy from the panel, read Add an application.

Before you start

• A person with access to the hypervisor did the bootstrap: the Incus hypervisor runs, and it has the base image and the client certificate of the deploy.
• Your address is in ADMIN_SOURCES, or you are on the VPN of the hosting provider. Without this, the admin web UIs and the Incus API refuse you.
• For a deploy from a workstation, you are a member of the fediversity-admins group in the lldap directory of the hosting provider.
• Your Nix has the features nix-command and flakes enabled. The nix commands in this guide need them; Prerequisites tells how to enable them.

Pages

• Check and test a change: check a change without a deploy, write a NixOS test, and test a feature branch or an operator branch.
• Deploy: receive the alerting notifications, find the credentials of the state backend, and deploy from CI or from a workstation.
• Log in with a certificate: get an SSH certificate from OpenBao, trust a CA, and rotate the CA.
• Update nixpkgs: update the nixpkgs pin, and the packages and the state that follow nixpkgs.
• Make a release: make a release, and set up the signing key.
• Read the logs: find the logs of the nodes and of the deploys.