docs: add a tutorial

Sponsored-by: author

1 files changed, 115 insertions, 0 deletions

diff --git a/tutorial.md b/tutorial.md
new file mode 100644
index 0000000..e9bbee2
--- /dev/null
+++ b/tutorial.md
@@ -0,0 +1,115 @@
+# Install Debian on a bare metal system with v-i
+
+You need:
+
+- a USB drive, at least 4 GB
+- a PC that supports UEFI
+- backups: _all drives_ in the PC will be wiped from data
+
+The steps:
+
+1. Download the installer image from
+   <https://files.liw.fi/v-i/v-i.img.xz>. You can use `curl` or `wget`
+   or your web browser. Use **one of** the following commands:
+
+    ~~~sh
+    curl https://files.liw.fi/v-i/v-i.img.xz > v-i.img.xz
+    wget -c https://files.liw.fi/v-i/v-i.img.xz
+    ~~~
+
+2. Unpack the image.
+
+   ~~~sh
+   unxz v-i.img.xz
+   ~~~
+
+3. Insert USB drive and write the image to the stick. I prefer GNOME
+   Disks for this, but dd will work. Look up the device of the USB
+   stick: run `sudo dmsg -T` and look for relevant kernel message, or
+   use GNOME Disks, or something else. Replace the actual device for
+   `sdx` below, then run the following command:
+
+    ~~~sh
+    dd if=v-i.img bs=1M oflag=direct status=progress of=/dev/sdx
+    ~~~
+
+4. You will need to be able to log into the installer, once it's
+   running. You can do this by logging in as `root` without a password
+   on the virtual console, or you can use SSH. Note that SSH logins as
+   root _must_ use key authentication: passwords _do not work_.
+
+   For SSH login you need to install your SSH public key into the
+   `authorized_keys` file. If you want that, use **one of** the
+   following two:
+
+   - run a script to install it on the USB drive you've just written
+     the image to:
+
+     ~~~sh
+     sudo bash set-authorized-keys /dev/sdx path/to/your/key.pub
+     ~~~
+
+   - create a second stick with a file system with the label
+     `v-i-config` and a file called `authorized_keys`, and have that
+     in a USB port when you boot from the v-i USB drive
+
+5. Make sure everything has been written to the USB drive. Again, I
+   prefer GNOME Disks for this, but from the command line:
+
+    ~~~sh
+    sync
+    eject /dev/sdx
+    ~~~
+
+6. Move the USB drive to the target machine and boot off the drive.
+   How this happens varies from machine to machine. On my Thinkpad, I
+   press F12 at the POST screen and then choose the right drive from
+   the boot menu.
+
+7. Wait for the system to boot. Log in as root, either from the
+   virtual console (no password), or via SSH.
+
+8. Create a target specification file `foo-target.yaml`. The name can
+   be anything, but it must be valid YAML. In the example below, there
+   are two NVMe drives. An extra logical volume is created. An extra
+   Ansible playbook is run against the target system. The given SSH
+   public key is installed into the `authorized_keys` file for the
+   `root` user on the target system. All drives will be encrypted
+   using LUKS, with the password "hunter2".
+
+    ~~~yaml
+    luks: hunter2
+    drive: /dev/nvme0n1
+    extra_drives:
+      - /dev/nvme1n1
+    hostname: foo
+    extra_playbooks:
+      - foo-playbook.yml
+    ansible_vars:
+      user_pub: |
+       ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPQe6lsTapAxiwhhEeE/ixuK+5N8esCsMWoekQqjtxjP liw personal systems
+    extra_lvs:
+      - name: vms
+        size: 1T
+        fstype: ext4
+        mounted: /mnt/vms
+    ~~~
+
+9. Install. Add the `--verbose` option to `./v-i` if you want to know
+   what's happening. The first time you run this on a given v-i USB
+   drive, it takes a while: it runs `vmdebootstrap` and that is just
+   slow. However, the output is cached, so further runs are faster.
+
+    ~~~sh
+    rm -f install.log
+    ./v-i foo-target.yaml
+    ~~~
+
+10. Reboot into the installed system.
+
+11. Finish configuring the system in whatever way you like to do that.
+    You can log into it via SSH as root. I use Ansible.
+
+    Remember to change the LUKS password for each drive.
+
+12. Optional: Let me know how it went.