Tools

A primer for each tool the fleet is built from, and how-tos for the changes you make with it. The build guide tells you what to do and links here for why it works.

Every primer has the same sections: what the tool is, the ideas you need, how the fleet uses it, how to find your way around, how to make a change, and what to check when it goes wrong. The first three are what the build guide assumes, and it links to them where each tool first appears. Come back for the rest when you have something to change.

A how-to is one task from start to finish. Each one carries a status line, since none has been run against a live fleet yet, and lists what is still unconfirmed at its end.

For a single term, see the glossary. For how the tools fit together, see The fleet at a glance.

Building a host

These tools take a host from nothing to running containers.

Tool	Its job	How-tos
OpenTofu	Creates the VM in Proxmox	Reading a plan before applying, Changing a VM's CPU or memory, Removing a VM
NixOS	The operating system, built from a description	Changing a host's setting, Opening a firewall port, Adding a module to the flake
Ansible	Runs the other tools in order	Running part of a run, Adding a variable to the inventory, Reading a failed run
Semaphore UI	Starts runs from a web page and keeps their history	Adding a Task Template, Reading a task's log
sops with age	Keeps secrets in git, encrypted	Adding a secret for the hosts

Running containers

Tool	Its job	How-tos
Docker Compose	Defines a set of containers in a file	Looking inside a stack on a host
Komodo	Deploys the stacks to every host	Adding a stack to a host, Writing a new stack, Updating a container image

Serving what runs

Tool	Its job	How-tos
Traefik	Routes a hostname to its container, with TLS	Adding a route to a service, Publishing a route beyond its VM
Authentik	One sign-in for every web interface	Putting an application behind a sign-in, Adding a user and a group, Signing in to an application with OpenID Connect
VictoriaMetrics	Stores metrics and logs, and raises alerts	Adding a scrape target, Adding an alert rule, Searching the logs
step-ca	The fleet's own certificate authority	Trusting the fleet's root certificate
Stalwart	Mailboxes	Adding a mailbox, Adding a mail domain

Defined, not deployed

fleet-stacks defines these two stacks, and no host in the build guide runs them. Each primer says what adding it would take.

Tool	Its job
CrowdSec	Bans addresses that behave like attackers
Technitium	A DNS server

Where to start

You need not read every primer before you build. If you want to read ahead, follow the order the build guide meets them: Ansible, OpenTofu, NixOS, and sops for the first run, then Docker Compose and Komodo, then Semaphore. Traefik and Authentik come next, when the fleet leaves bootstrap mode. The rest can wait until you build the host that runs them.