TODO: booting issues

4 files changed, 38 insertions, 0 deletions

diff --git a/docs/ideas.md b/docs/ideas.md
index 7c96301..dfd549b 100644
--- a/docs/ideas.md
+++ b/docs/ideas.md
@@ -1,5 +1,7 @@
 # Ideas
 
+## Misc
+
 * `hydractl`:
   * `mount-kvmx-supervised`: open encrypted volumes from supervised [kvmx][] guests.
 * `hydra`:
diff --git a/docs/todo.md b/docs/todo.md
new file mode 100644
index 0000000..b01437e
--- /dev/null
+++ b/docs/todo.md
@@ -0,0 +1,6 @@
+# TODO
+
+## hydractl
+
+* [ ] Provision:
+    * [ ] Fix booting issues detailed [here](tpc.md#booting).
diff --git a/docs/tpc.md b/docs/tpc.md
index 12f83ba..96140a9 100644
--- a/docs/tpc.md
+++ b/docs/tpc.md
@@ -186,6 +186,35 @@ From another system, and with the cartridge mounted:
 
     hydractl umount-media $VOLNAME
 
+## Booting
+
+The current provisioning procedure (as of 2024-02) may yield into
+a partially bootable system, and may need some additional manual
+steps right after installation:
+
+    hydractl mount-media $VOLNAME
+    sudo chroot $DEST
+    update-initramfs -v -u
+    hydractl umount-media $VOLNAME
+
+During boot, at the `(initramfs)` prompt, type this to successfully
+unlock the encrypted volumes:
+
+    cryptsetup luksOpen /dev/mapper/volumename-root root
+    cryptsetup luksOpen /dev/mapper/volumename-swap swap
+    ^Ctrl-D
+
+Where `volumename` is `$VOLNAME`.
+
+Then, in the running system, do:
+
+    sudo update-initramfs -v -u
+
+With these steps, the system's boot procedure was fixed.
+
+But there are fixes be done at `hydractl provision` to produce fully working
+installations.
+
 ## Deploy
 
 Now it's time to boot the new system, log in with your user and deploy the complete
diff --git a/mkdocs.yml b/mkdocs.yml
index 9929a04..e62b5f0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -12,3 +12,4 @@ nav:
   - tpc.md
   - backups.md
   - ideas.md
+  - todo.md