Add builds.sr.ht image bootstrapping guide

1 files changed, 54 insertions, 22 deletions

diff --git a/builds.sr.ht/installation.md b/builds.sr.ht/installation.md
index 7eb0fe0..b6a7c92 100644
--- a/builds.sr.ht/installation.md
+++ b/builds.sr.ht/installation.md
@@ -68,31 +68,63 @@ source, this package is simply the `images` directory copied to
     $ docker build -t qemu -f qemu/Dockerfile .
 
 This will build a docker image named `qemu` which contains a statically linked
-build of qemu and nothing else. Next, build any of the images you need:
-
-    $ cd archlinux
-    $ sudo ./genimg
-    $ ../control archlinux sanity-check
-    $ cd ../debian/jessie
-    $ sudo ./genimg
-    $ ../../control debian/jessie sanity-check
-    ... and so on ...
-
-Note: some images may not build on your host system without the installation of
-extra tools, which may or may not be available for your host system. However,
-all images can be built on themselves, and a build.yml file is typically
-provided which can do the job if run in a similar environment as the target
-image.
+build of qemu and nothing else.
+
+## Bootstrapping our images
+
+A `genimg` script is provided for each image which can be run from a working
+image of that guest to produce a new image. You need to manually prepare a
+working guest of each image type (that is, to build the Arch Linux image you
+need a working Arch Linux installation to bootstrap from). Then you can run the
+provided `genimg` to produce the disk image. A `build.yml` file is also provided
+for each image to build itself on your build infrastructure once you have it set
+up. It's recommended that you set up cron jobs to build fresh images frequently.
 
 ## Creating new images
 
-If you require any additional images, you should write a `genimg` script which
-produces `root.img.qcow2`, `initrd`, and `kernel` files. You should also write a
-`functions` script, which is sourced by the control script for booting your
-image, installing packages, and so on. Review existing images for guidance, it
-should be possible to make virtually any kind of image (including non-Linux
-operating systems - the only hard requirement is an ssh daemon) with enough
-effort.
+If you require additional images, study the `control` script to understand how
+the top-level boot process works. You should then prepare a disk image for your
+new system (name it `root.img.qcow2`) and write a `functions` file. The only
+required function is `boot`, which should call `_boot` with any additional
+arguments you want to pass to qemu. If your image will boot up with no
+additional qemu arguments, this function will likely just call `_boot`. You can
+optionally provide a number of other functions in your `functions` file to
+enable various features:
+
+- To enable installing packages specified in the build manifest, write an
+  `install` function with the following usage:
+  `install [ssh port] [packages...]`
+- To enable adding third-party package repositories, write an `add_repository`
+  function: `add_repository [ssh port] [name] [source]`. The `source` is usually
+  vendor-specific, you can make this any format you want to encode repo URLs,
+  package signing keys, etc.
+
+In order to run builds, we require the following:
+
+- The disk should be able to boot itself up, make sure to install a bootloader
+  and set up partitions however you like.
+- Networking configured with IPv4 address `10.0.2.15/25` and gateway `10.0.2.2`.
+  Don't forget to configure DNS, too.
+- SSH listening on port 22 (the standard port) with passwordless login *enabled*
+- A user named `build` to log into SSH with, preferrably with uid 1000
+- Bash (temporary - we'll make this more generic at some point)
+
+Not strictly necessary, but recommended:
+
+- Set the hostname to `build`
+- Configure NTP and set the timezone to UTC
+- Add the build user to the sudoers file with `NOPASSWD: ALL`
+- In your `functions` file, set `poweroff_cmd` to a command we can SSH into the
+  box and use to shut off the machine. If you don't, we'll just kill the qemu
+  process.
+- It is also recommended to write a `sanity_check` function which takes no
+  arguments, but boots up the image and runs any tests necessary to verify
+  everything is working and return a nonzero status code if not.
+
+You will likely find it useful to read the scripts for existing build images as
+a reference. Once you have a new image, email the scripts to
+[`~sircmpwn/sr.ht-dev@lists.sr.ht`](https://lists.sr.ht/~sircmpwn/sr.ht-dev) so
+we can integrate them upstream!
 
 # Additional configuration