Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a documentation site #232

Merged
merged 29 commits into from
Oct 16, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
b0d6795
Add script to generate options documentation
barrucadu Oct 15, 2023
e63b153
Generate a basic reference documentation site
barrucadu Oct 15, 2023
0dfb3b0
Add action to deploy the documentation site
barrucadu Oct 15, 2023
937f720
Document `backups` module and options
barrucadu Oct 15, 2023
619cd59
Document `bookdb` module and options
barrucadu Oct 15, 2023
8395057
Document `bookmarks` module and options
barrucadu Oct 15, 2023
39f53fc
Document `concourse` module and options
barrucadu Oct 15, 2023
75f2091
Document `erase-your-darlings` module and options
barrucadu Oct 15, 2023
13c65ae
Document `finder` module and options
barrucadu Oct 15, 2023
fff7162
Document `foundryvtt` module and options
barrucadu Oct 15, 2023
cf99dd2
Document `minecraft` module and options
barrucadu Oct 15, 2023
3df848b
Document `pleroma` module and options
barrucadu Oct 15, 2023
9175af4
Document `resolved` module and options
barrucadu Oct 15, 2023
b4fd464
Document `rtorrent` module and options
barrucadu Oct 15, 2023
cc5f131
Document `umami` module and options
barrucadu Oct 15, 2023
539a512
Document the `oci-containers` module and options
barrucadu Oct 15, 2023
6bdd1ef
Document the shared module and options
barrucadu Oct 15, 2023
339acfe
Enforce options have descriptions
barrucadu Oct 15, 2023
adfdd30
Rename `resolved` options for consistency
barrucadu Oct 15, 2023
dddeae2
Rename `pleroma.pgTag` for consistency
barrucadu Oct 15, 2023
ffc6136
Rename `*.esTag` for consistency
barrucadu Oct 15, 2023
4b18a04
Rename `*.esPort` for consistency
barrucadu Oct 15, 2023
c957dec
Remove legacy `oci-containers.containers` options
barrucadu Oct 15, 2023
06c4a96
Most host documentation out of README
barrucadu Oct 15, 2023
8c3f92f
Document packages
barrucadu Oct 15, 2023
9cc0d52
Move "Setting up a new host" out of the README
barrucadu Oct 15, 2023
9144a76
Editing pass to make module docs consistent
barrucadu Oct 16, 2023
68793f8
Editing pass to make option docs consistent
barrucadu Oct 16, 2023
807aa37
Add a link to the documentation from the README
barrucadu Oct 16, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,19 @@ jobs:
nix run .#fmt
nix run .#lint
git diff --exit-code
- name: Check mdbook-admonish changes are not committed
run: |
if grep -q "do not edit: managed by \`mdbook-admonish install\`" docs/book.toml; then
echo "remove generated mdbook-admonish lines from docs/books.toml" >&2
exit 1
fi

test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v23
with:
nix_path: nixpkgs=channel:nixos-unstable
- name: Check documentation site builds
run: nix run .#documentation
51 changes: 51 additions & 0 deletions .github/workflows/deploy-documentation.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
name: Deploy documentation site

on:
# Runs on pushes targeting the default branch
push:
branches: ["master"]

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false

jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Install nix
uses: cachix/install-nix-action@v23
with:
nix_path: nixpkgs=channel:nixos-unstable
- name: Build
run: nix run .#documentation
- name: Upload artifact
uses: actions/upload-pages-artifact@v2

# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/_site
208 changes: 2 additions & 206 deletions README.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ nix run .#fmt
nix run .#lint
```

See [the documentation](https://nixfiles.docs.barrucadu.co.uk).

[NixOS]: https://nixos.org
[flakes]: https://nixos.wiki/wiki/Flakes

Expand Down Expand Up @@ -65,212 +67,6 @@ default.

[wiping `/` on boot]: https://grahamc.com/blog/erase-your-darlings

### Hosts

Currently I have 3 NixOS machines. The naming convention is:

- **Local machines:** beings (gods, people, etc) of the Cthulhu Mythos.
- **Remote machines:** places of the Cthulhu Mythos.

#### azathoth

This is my desktop computer.

It dual-boots Windows and NixOS, so it doesn’t run any services, as they won't
be accessible half of the time. I don't bother backing up either OS: everything
I care about is in Syncthing, on GitHub, or on some other cloud service (eg,
Steam).

#### carcosa

This is a VPS (hosted by Hetzner Cloud).

It serves [barrucadu.co.uk][] and other services on it, such as [a bookdb
instance][] and [my blog][]. Websites are served with Caddy, with certs from
Let's Encrypt.

It's set up in "erase your darlings" style, so most of the filesystem is wiped
on boot and restored from the configuration, to ensure there's no accidentally
unmanaged configuration or state hanging around. However, it doesn't reboot
automatically, because I also use this server for a persistent IRC connection.

[barrucadu.co.uk]: https://www.barrucadu.co.uk/
[a bookdb instance]: https://bookdb.barrucadu.co.uk/
[my blog]: https://memo.barrucadu.co.uk/

#### nyarlathotep

This is my home server.

It runs writable instances of the bookdb and bookmarks services, which have any
updates copied across to carcosa hourly; it acts as a NAS; and it runs a few
utility services, such as a dashboard of finance information from my hledger
journal, and a script to automatically tag and organise new podcast episodes or
CD rips which I copy over to it.

Like carcosa, this host is set up in "erase your darlings" style but, unlike
carcosa, it automatically reboots to install updates: so that takes effect
significantly more frequently.


Setting up a new host
---------------------

See also [the NixOS installation instructions](https://nixos.org/manual/nixos/stable/index.html#ch-installation).

1. Create & format partitions
1. **Optional:** Configure wiping / on boot (pre-first-boot steps)
1. Install NixOS with the standard installer
1. Reboot into the installed system
1. Clone this repo to `/etc/nixos`
1. Move the generated configuration to `hosts/<hostname>/` and edit to fit repo conventions
1. Add an entry for the host to `flake.nix`
1. **Optional:** Add DNS records
1. **Optional:** Configure secrets
1. **Optional:** Configure wiping / on boot (post-first-boot steps)
1. **Optional:** Configure backups
1. **Optional:** Generate SSH key
1. Build the new system configuration with `sudo nixos-rebuild switch --flake '.#<hostname>'`
1. Reboot
1. Commit, push, & merge

### Optional: Configure wiping / on boot

Before installing NixOS, create the `local` pool and datasets:

```bash
zpool create -o mountpoint=legacy -o autotrim=on local <device>

zfs create -o mountpoint=legacy local/volatile
zfs create -o mountpoint=legacy local/volatile/root

zfs create -o mountpoint=legacy local/persistent
zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/home
zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/nix
zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/persist
zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/var-log
```

Take a snapshot of the empty root dataset:

```bash
zfs snapshot local/volatile/root@blank
```

Mount all the filesystems under `/mnt`:

```bash
mount -t zfs local/volatile/root /mnt

mkdir /mnt/boot
mkdir /mnt/home
mkdir /mnt/nix
mkdir /mnt/persist
mkdir -p /mnt/var/log

mount /dev/<boot device> /mnt/boot
mount -t zfs local/persistent/home /mnt/home
mount -t zfs local/persistent/nix /mnt/nix
mount -t zfs local/persistent/persist /mnt/persist
mount -t zfs local/persistent/var-log /mnt/var/log
```

Then run the installer, making sure to add ZFS details to the generated configuration:

```nix
networking.hostId = "<random 32-bit hex value>";
boot.supportedFilesystems = [ "zfs" ];
```

**After first boot:** copy any needed files (eg, SSH host keys) to the
appropriate place in `/persist`, add the user password to the secrets, and set
up `nixfiles.eraseYourDarlings`:

```nix
nixfiles.eraseYourDarlings.enable = true;
nixfiles.eraseYourDarlings.machineId = "<contents of /etc/machine-id>";
nixfiles.eraseYourDarlings.barrucaduPasswordFile = config.sops.secrets."users/barrucadu".path;
sops.secrets."users/barrucadu".neededForUsers = true;
```

### Optional: Add DNS records

Add `A` / `AAAA` records to [the ops repo](https://github.com/barrucadu/ops) and
apply the change via [Concourse](https://cd.barrucadu.dev/).

### Optional: Configure secrets

After first boot, generate an age public key from the host SSH key:

```bash
nix-shell -p ssh-to-age --run 'ssh-keyscan <hostname>.barrucadu.co.uk | ssh-to-age'
```

Add a new section with this key to `.sops.yaml`:

```yaml
creation_rules:
...
- path_regex: hosts/<hostname>/secrets(/[^/]+)?\.yaml$
key_groups:
- age:
- *barrucadu
- '<key>'
```

Enable sops in the host configuration:

```nix
sops.defaultSopsFile = ./secrets.yaml;
```

### Optional: Configure backups

All hosts which run any sort of service with data I care about should take
automatic backups.

Firstly, add the backup credentials to the secrets:

```bash
nix run .#secrets
```

Then enable backups in the host configuration:

```nix
nixfiles.backups.enable = true;
nixfiles.backups.environmentFile = config.sops.secrets."nixfiles/backups/env".path;
sops.secrets."nixfiles/backups/env" = { };
```

Most services define their own backup scripts. For any other needs, write a
custom script:

```nix
nixfiles.backups.scripts.<name> = ''
<script which copies files to backup to the current working directory>
'';
```

### Optional: Generate SSH key

Generate an ed25519 SSH key:

```bash
ssh-keygen -t ed25519
```

**If the host should be able to interact with GitHub:** add the public key to
the GitHub user configuration *as an SSH key*.

**If the host should be able to push commits to GitHub:** add
the public key to the GitHub user configuration *as a signing key*, and also add
it to [the allowed_signers
file](https://github.com/barrucadu/dotfiles/blob/master/dot_config/git/allowed_signers.tmpl).

**If the host should be able to connect to other machines:** add the public key
to `shared/default.nix`.


Tools
-----
Expand Down
9 changes: 9 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
book

# generated by the build script
src/README.md
src/hosts.md
src/modules.md
src/options.md
src/packages.md
mdbook-admonish.css
17 changes: 17 additions & 0 deletions docs/book.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[book]
title = "nixfiles"
authors = ["Michael Walker (barrucadu)"]
description = "My NixOS configuration and assorted other crap, powered by flakes."
language = "en"
multilingual = false

[build]
create-missing = false

[output.html]
git-repository-url = "https://github.com/barrucadu/nixfiles"
cname = "nixfiles.docs.barrucadu.co.uk"

[preprocessor.admonish]
on_failure = "bail"
command = "mdbook-admonish"
14 changes: 14 additions & 0 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Summary

- [README](./README.md)

# Reference

- [Hosts](./hosts.md)
- [Modules](./modules.md)
- [Options](./options.md)
- [Packages](./packages.md)

# Runbooks

- [Set up a new host](./runbooks/set-up-a-new-host.md)
Loading