doc clean

This commit is contained in:
ari committed 2026-10-09 14:35:12 -04:00
1 parent c2a7f94821
commit 30427e3975
34 files changed
+1119 -1758

No files matched your search

+9 -34
View File
@@ -1,15 +1,4 @@
# hermenix setup — guided host-side provisioning.
#
# Walks through every prerequisite check, disk creation, cache signing key,
# local.nix, image build and image write. Safe to re-run; each step checks
# what already exists. Never runs nixos-rebuild.
#
# Depends on: lib/common.nu, lib/guest.nu.
# `truncate -s` treats a bare number as bytes, not gigabytes — the size
# prompts' own defaults ("80G", "20G") make gigabytes the obvious intent, so
# normalize a bare integer answer to that rather than silently creating a
# byte-sized disk. Anything with an existing suffix passes through as-is.
# Bare `truncate -s N` is bytes; prompts default to gigabytes.
def normalize-size [s: string] {
try {
let n = $s | into int
@@ -19,28 +8,20 @@ def normalize-size [s: string] {
}
}
# Run a command, sudo-prefixed unless already root (set once via
# $env.HERMENIX_NEED_SUDO at the top of `main setup`). Fails loudly, like any
# other external command, if the command fails.
def priv [...args: string] {
let need_sudo = $env.HERMENIX_NEED_SUDO? | default false
let argv = if $need_sudo { ["sudo"] ++ $args } else { $args }
^($argv | first) ...($argv | skip 1)
}
# Same as priv, but captures stdout/exit code instead of failing the script.
def priv-out [...args: string] {
let need_sudo = $env.HERMENIX_NEED_SUDO? | default false
let argv = if $need_sudo { ["sudo"] ++ $args } else { $args }
(^($argv | first) ...($argv | skip 1) | complete)
}
# Guided host-side setup: disks, cache signing key, /etc/hermenix/local.nix,
# build and write the bootstrap image. Safe to re-run — every step checks
# what's already done and offers to skip. Never runs nixos-rebuild. Works
# from any directory - no local checkout of this repo needed.
def "main setup" [
--flake: string = "git+ssh://gitea@minipc1.lab.internal:22/ari/hermenix.git"
--flake: string = "git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git"
--clean # stop the VM and delete existing disk images + UEFI vars first, for a fully fresh start
] {
$env.HERMENIX_NEED_SUDO = ((^id -u | str trim) != "0")
@@ -100,10 +81,7 @@ def "main setup" [
do -i { priv rm "-f" $"($base)/system/system.raw" } | complete | ignore
do -i { priv rm "-f" $"($base)/state/state.raw" } | complete | ignore
do -i { priv rm "-f" $"($base)/OVMF_VARS.fd" } | complete | ignore
# A fresh state disk means a fresh SSH host key on next boot - drop the
# stale known_hosts entry now so the next connect doesn't fail on a
# host-key mismatch. Not run through priv: this is the invoking user's
# own ~/.ssh/known_hosts, not a root-owned path.
# Fresh state disk => fresh SSH host key; drop stale known_hosts (user's, not root's).
do -i { ^ssh-keygen -R hermes } | complete | ignore
ok "cleaned existing disk images and stale known_hosts entry"
}
@@ -375,8 +353,7 @@ def "main setup" [
\};
"
note $"detected uplink: ($uplink) — check that's right before rebuilding"
note "network.bridged = true instead puts the guest on your LAN (own DHCP"
note "address, every opened port reachable from the LAN) - see the README."
note "network.bridged = true puts the guest on your LAN — see docs/NETWORK.md."
print $"
Then:
@@ -385,20 +362,18 @@ def "main setup" [
hermenix vm console (ansi dark_gray)# watch it boot(ansi reset)
hermenix vm ssh (ansi dark_gray)# get in(ansi reset)
Inside the guest, in this order:
Inside the guest (hermenix side):
lsblk -f (ansi dark_gray)# CHECK LABELS match guest/hardware.nix(ansi reset)
determinate-nixd login (ansi dark_gray)# FlakeHub Cache(ansi reset)
sudo nix flake lock /etc/nixos
(ansi dark_gray)# hermes installs itself automatically - give it a few minutes(ansi reset)
hermes setup
hermes gateway install
(ansi dark_gray)# hermes CLI installs unattended — give it a few minutes(ansi reset)
Back on the host:
Configure Hermes itself with the upstream CLI/docs (providers, gateway, …).
From the host, once the gateway unit exists:
hermenix ctl units (ansi dark_gray)# confirm the gateway unit name(ansi reset)
hermenix ctl units
hermenix ctl status
hermenix ctl soul
"
warn "Check the disk labels before the guest's first nixos-rebuild. If they"