diff --git a/README.md b/README.md
index 257e36c..61e43ac 100644
--- a/README.md
+++ b/README.md
@@ -7,13 +7,14 @@ single flake.
 
 Defined in the host table in [`flake.nix`](./flake.nix):
 
-| Configuration         | System           | Machine                                                                     |
-| --------------------- | ---------------- | --------------------------------------------------------------------------- |
-| `lyrathorpe-mbp`      | `aarch64-linux`  | MacBook Pro (Apple Silicon, Asahi)                                          |
-| `lyrathorpe-t400`     | `x86_64-linux`   | ThinkPad T400 — [install notes](./system/machine/T400/README.md)            |
-| `lyrathorpe-macpro31` | `x86_64-linux`   | Mac Pro 3,1, desktop — [install notes](./system/machine/MacPro31/README.md) |
-| `emmathorpe-edaas`    | `x86_64-linux`   | Work WSL box (NixOS-WSL)                                                    |
-| `lyrathorpe-mac`      | `aarch64-darwin` | macOS (nix-darwin)                                                          |
+| Configuration         | System           | Machine                                                                                                              |
+| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `lyrathorpe-mbp`      | `aarch64-linux`  | MacBook Pro (Apple Silicon, Asahi)                                                                                   |
+| `lyrathorpe-t400`     | `x86_64-linux`   | ThinkPad T400 — [install notes](./system/machine/T400/README.md)                                                     |
+| `lyrathorpe-macpro31` | `x86_64-linux`   | Mac Pro 3,1, desktop — [install notes](./system/machine/MacPro31/README.md)                                          |
+| `emmathorpe-edaas`    | `x86_64-linux`   | Work WSL box (NixOS-WSL)                                                                                             |
+| `lyrathorpe-rpi5`     | `aarch64-linux`  | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](./system/machine/RPi5/README.md) |
+| `lyrathorpe-mac`      | `aarch64-darwin` | macOS (nix-darwin)                                                                                                   |
 
 Shared layers: `lyrathorpe/home` (home-manager: shell, git, editor),
 `system/modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches),
@@ -41,11 +42,13 @@ darwin-rebuild switch --flake .#lyrathorpe-mac
 ## Login / greeter
 
 Graphical (Sway) hosts log in through a Wayland greeter — `greetd` running
-ReGreet inside the `cage` kiosk compositor — configured centrally in
+ReGreet inside the `cage` kiosk compositor — implemented in
 [`lyrathorpe/swaywm.nix`](./lyrathorpe/swaywm.nix), gated on
-`features.swayDesktop.enable`. The greeter is forced to Dvorak to match the
-console and Sway session. Hosts with `features.swayDesktop.enable = false` (the
-WSL work box) keep plain TTY login. The target account needs a password
+`features.swayDesktop.enable` (the option is declared in
+[`system/modules/features.nix`](./system/modules/features.nix), so headless hosts
+can leave it off without importing `swaywm.nix`). The greeter is forced to Dvorak
+to match the console and Sway session. Headless hosts (the WSL work box and the
+Raspberry Pi server) keep plain TTY login. The target account needs a password
 (`passwd <user>`) before it can log in.
 
 ## MacBook (Asahi) firmware
diff --git a/system/machine/RPi5/README.md b/system/machine/RPi5/README.md
new file mode 100644
index 0000000..5238292
--- /dev/null
+++ b/system/machine/RPi5/README.md
@@ -0,0 +1,68 @@
+# Raspberry Pi 5 (`lyrathorpe-rpi5`)
+
+Headless `aarch64-linux` server with two roles:
+
+- **Docker host** — daemon exposed over the network (`docker.nix`).
+- **nginx reverse proxy** — declarative `virtualHosts` (`reverse-proxy.nix`).
+
+## Install
+
+1. Flash a NixOS `aarch64` SD image (or USB) and boot the Pi. The
+   `raspberry-pi-5` profile from `nixos-hardware` (wired in the flake host table)
+   supplies the kernel, firmware and device tree; boot is U-Boot + extlinux.
+2. Partition/mount the target, then **regenerate the hardware config on the
+   device** and replace the committed placeholder:
+   ```sh
+   nixos-generate-config --root /mnt
+   # copy /mnt/etc/nixos/hardware-configuration.nix over
+   # system/machine/RPi5/hardware-configuration.nix in this repo, then commit
+   ```
+   `hardware-configuration.nix` in this directory is a **placeholder** committed
+   only so the host evaluates in CI. The machine will not boot correctly until it
+   is replaced with the generated one.
+3. Set the host name to match the flake attribute (already done in
+   `configuration.nix`: `lyrathorpe-rpi5`) and build:
+   ```sh
+   sudo nixos-rebuild switch --flake .#lyrathorpe-rpi5
+   # or, once the hostname is live:
+   nh os switch
+   ```
+4. Give the login user a password (`passwd lyrathorpe`) and confirm the key in
+   `system/modules/ssh.nix` is the one you will connect with.
+
+## Docker socket (security)
+
+The daemon listens on **plain TCP `2375`, no TLS, no auth**. Access is
+root-equivalent on this host. The only protection is the nftables rule in
+`docker.nix`, which accepts `2375` **only** from the trusted LAN subnet
+(`10.187.1.0/24` by default — change it to match your network). Do not widen
+that subnet to anything untrusted.
+
+From a LAN client:
+
+```sh
+export DOCKER_HOST=tcp://lyrathorpe-rpi5:2375
+docker info
+```
+
+The secure upgrade path is mutual TLS on `2376` (`--tlsverify` with a CA and
+client certs); it needs out-of-band cert provisioning and is intentionally not
+wired here.
+
+## Adding a reverse-proxy site
+
+Each proxied service is a Nix entry in `reverse-proxy.nix`:
+
+```nix
+services.nginx.virtualHosts."app.example.lan" = {
+  # enableACME = true; forceSSL = true;   # once a DNS name + cert exist
+  locations."/" = {
+    proxyPass = "http://127.0.0.1:8080";  # e.g. a local container
+    proxyWebsockets = true;
+  };
+};
+```
+
+The example vhost is HTTP-only by design. Turn on `enableACME`/`forceSSL`
+per-vhost once the host has a real DNS name and the ACME challenge can be met;
+`443` is already open in the firewall.