diff options
| -rw-r--r-- | builds.sr.ht/index.md | 2 | ||||
| -rw-r--r-- | builds.sr.ht/installation.md | 76 |
2 files changed, 55 insertions, 23 deletions
diff --git a/builds.sr.ht/index.md b/builds.sr.ht/index.md index e635a71..75d5873 100644 --- a/builds.sr.ht/index.md +++ b/builds.sr.ht/index.md @@ -70,7 +70,7 @@ A [full reference](manifest.md) for build manifests is available. Presently, the following build images are available: -- alpine +- alpine/edge - archlinux - debian/buster - debian/jessie 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 |