Self-host Overalls

Overalls runs on hardware you control and nowhere else. This guide covers going from a bare-metal server to signing in and starting your first machine. It's a summary: each page links to the full operator documentation in the repository, which is the source of truth.

Audience

Operators who are comfortable with NixOS, SSH and PostgreSQL

Time

An afternoon for one host, if your DNS and email relay are ready

What you're building

• Marshall: the web app and control plane, behind HAProxy with ACME certificates, using PostgreSQL and an SMTP relay.
• Lilly on every host: runs Firecracker guests on a ZFS pool.
• Porsche: the SSH management gateway. Audi: DNS, guest SSH and public web apps.
• Optional edge services: Brady (egress cache), Enrico (GitHub mirror), Ziggy (inference) and Galileo (integrations).

Every role can run on one host. A deployment with redundancy spreads Marshall across at least three hosts with a highly available database.

Your fleet is a Git repository

Hosts don't take commands from your laptop. Each one polls a branch of a Git repository you control, builds the exact revision, applies migrations, switches and checks its own health. So step one is to fork Overalls and make the fleet yours:

1. Fork github.com/ghuntley/overalls ↗ to a Git server your hosts can reach over SSH.
2. Replace the example hosts in fleet/hosts/ with your own. fleet/hosts/overalls/ is a complete, working reference.
3. Put your operators and recovery users in nix/users.nix, and the public addresses allowed to reach your fleet in nix/allowed-hosts.nix.
4. Commit and push. Encrypted secrets live under secrets/; plaintext never goes in the repo.

Some modules, options and units still use the project's former codename kittens, for example services.kittensAutoUpdate. Type them exactly as shown.

Requirements

Hosts

x86_64 bare metal with a working /dev/kvm. The bootstrap tool knows Hetzner dedicated and EC2 bare metal. The target needs root (or passwordless sudo), Python 3, OpenSSH, lsblk and iproute2.

Disks

Two system disks on Hetzner, or the root EBS volume on EC2. Guest disks live on native ZFS.

Database

PostgreSQL, reached over verified TLS

Email

An SMTP relay with authentication and verified TLS (implicit TLS or STARTTLS), for magic-link sign-in

DNS

A domain you control. The apex points at your Marshall hosts and apps.<your-domain> is delegated to Audi. See Set up DNS.

Laptop

Nix with flakes, a checkout of your fork, and an Ed25519 operator SSH key

The path

1. Overview and requirements (this page)
2. Provision a host: discover, review, plan, install, enroll
3. Deploy the control plane: modules, secrets, database, email, TLS
4. Set up DNS: apex records and the Audi delegation
5. Enroll hosts and images: Lilly credentials, guest images, Porsche
6. Your first machine: sign in, SSH keys, CLI, terminal
7. Day-two operations: updates, drains, backups, logs

Full reference: docs/deployment.md ↗