docs/administrative-access.md

@@ -28,18 +28,18 @@ People with admin access to the infrastructure are added to [`logins/admins.nix`
 SSH is not reachable from the open internet. Instead, SSH Port 22 is protected by a wireguard VPN network. Thus, to get root access on the servers, at least two pieces of information have to be added to the admins config:
 
 1. **SSH Public key**: self-explanatory. Add your public key to your user attrset under `sshPubKeys`.
-2. **Wireguard device**: each wireguard device has two parts: the public key and the IP addresses it should have in the wireguard network. The pub.solar wireguard network is spaced under `10.7.6.0/24` and `fd00:fae:fae:fae:fae::/80`. To add your device, it's best to choose a free number between 200 and 255 and use that in both the ipv4 and ipv6 ranges: `10.7.6.<ip-address>/32` `fd00:fae:fae:fae:fae:<ip-address>::/96`. For more information on how to generate keypairs, see [the NixOS Wireguard docs](https://nixos.wiki/wiki/WireGuard#Generate_keypair).
+2. **Wireguard device**: each wireguard device has two parts: the public key and the IP addresses it should have in the wireguard network. The pub.solar wireguard network uses the subnets `10.7.6.0/24` and `fd00:fae:fae:fae:fae::/80`. To add your device, it's best to choose a free number between 200 and 255 and use that in both the ipv4 and ipv6 ranges: `10.7.6.<ip-address>/32` `fd00:fae:fae:fae:fae:<ip-address>::/96`. For more information on how to generate keypairs, see [the NixOS Wireguard docs](https://nixos.wiki/wiki/WireGuard#Generate_keypair).
 
 One can access our hosts using this domain scheme:
 
 ```
-ssh barkeeper@<hostname>.wg.pub.solar
+ssh <unix-username>@<hostname>.wg.pub.solar
 ```
 
 So, for example for `nachtigall`:
 
 ```
-ssh barkeeper@nachtigall.wg.pub.solar
+ssh teutat3s@nachtigall.wg.pub.solar
 ```
 
 Example NixOS snippet for WireGuard client config

docs/deploying.md

@@ -7,16 +7,29 @@ be manually deployed.
 To deploy, make sure you have a [working development shell](./development-shell.md).
 Then, run `deploy-rs` with the hostname of the server you want to deploy:
 
+### Dry-run
+
+Use `--dry-activate` to show a diff of updated packages and all services that
+would be restarted by the update. This will also put all files in place without
+switching to the new generation, enabling a quick switch to the new config at a
+later moment.
+
 For nachtigall.pub.solar:
 
 ```
-deploy --targets '.#nachtigall' --magic-rollback false --auto-rollback false --keep-result --result-path ./results
+deploy --targets '.#nachtigall' --ssh-user <unix-username> --magic-rollback false --auto-rollback false --keep-result --result-path ./results --dry-activate
+```
+
+After reviewing the changes, apply the update with:
+
+```
+deploy --targets '.#nachtigall' --ssh-user <unix-username> --magic-rollback false --auto-rollback false --keep-result --result-path ./results
 ```
 
 For metronom.pub.solar (aarch64-linux):
 
 ```
-deploy --targets '.#metronom' --magic-rollback false --auto-rollback false --keep-result --result-path ./results --remote-build
+deploy --targets '.#metronom' --ssh-user <unix-username> --magic-rollback false --auto-rollback false --keep-result --result-path ./results --remote-build
 ```
 
 Usually we skip all rollback functionality, but if you want to deploy a change
@@ -25,9 +38,6 @@ that might lock you out, e.g. to SSH, it might make sense to set these to `true`
 To skip flake checks, e.g. because you already ran them manually before
 deployment, add the flag `--skip-checks` at the end of the command.
 
-`--dry-activate` can be used to only put all files in place without switching,
-to enable switching to the new config quickly at a later moment.
-
 We use `--keep-result --result-path ./results` to keep the last `result`
 symlink of each `deploy` from being garbage collected. That way, we keep builds
 cached in the Nix store. This is optional and both flags can be removed if disk

docs/garage.md

@@ -8,7 +8,7 @@ Requirements:
 - [Setup WireGuard](./administrative-access.md#ssh-access) for hosts: `trinkgenossin`, optionally: `delite`, `blue-shell`
 
 ```
-ssh barkeeper@trinkgenossin.wg.pub.solar
+ssh <unix-username>@trinkgenossin.wg.pub.solar
 ```
 
 ```
@@ -58,7 +58,7 @@ Further reading:
 ### Notes on manual setup steps
 
 ```
-ssh barkeeper@trinkgenossin.wg.pub.solar
+ssh <unix-username>@trinkgenossin.wg.pub.solar
 
 # Add a few spaces to avoid leaking the secret to the shell history
     export GARAGE_RPC_SECRET=<secret-in-keepass>

docs/nix-flake-updates.md

@@ -41,3 +41,7 @@ wrapped-ruby-mastodon-gems: 4.2.1 → 4.2.3
 zfs-kernel: 2.2.1-6.1.64 → 2.2.2-6.1.66
 zfs-user: 2.2.1 → 2.2.2
 ```
+
+### Deploying updates
+
+See [deploying.md](./deploying.md).