Merge branch 'readme'

.github/workflows/sanity.yaml

@@ -11,6 +11,9 @@ jobs:
     - name: The example's specification is clean
       run: scripts/is-clean example/openbsd.toml
 
+    - name: The example's README is clean
+      run: scripts/is-clean example/README.md
+
   sanity-script:
     runs-on: ubuntu-latest
     container:

README.md

@@ -1,12 +1,23 @@
 # OpenBSD image builder
 [![Tests](https://github.com/rootmos/openbsd/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/rootmos/openbsd/actions/workflows/tests.yaml)
 
-An [OpenBSD](https://www.openbsd.org/) image builder, or: a love letter to OpenBSD and [Qemu](https://www.qemu.org/) made with blood sweat and tears.
+An [OpenBSD](https://www.openbsd.org/) image builder.
+
+Or a love letter to OpenBSD made with blood sweat and tears.
+
+Or one way tame [Qemu](https://www.qemu.org/) and [autoinstall](https://man.openbsd.org/autoinstall.8) using [Python's asyncio](https://docs.python.org/3/library/asyncio.html).
+
+## TL;DR
+```shell
+./openbsd build disk.img
+./openbsd ssh disk.img
+```
 
 ## Design goals
-* configuration-less playground for reluctant hackers
-* audit-trail: specification controls everything
-* run in unprivileged mode
-* minimal dependencies: newish python (>=3.11) and qemu (optionally [signify](https://man.openbsd.org/signify) and socat)
-* cloud friendly (AWS)
-* stable over time: convenient (read doable) to add new versions
+* Configuration-less: playground for reluctant hackers
+* Audit-trail friendly: the specification file controls everything
+* Run in unprivileged mode: no more sudo
+* Minimal dependencies: newish Python (>=3.11) and Qemu, i.e. no pip only standand library
+  - optionally [signify](https://man.openbsd.org/signify) and socat
+* Cloud friendly: upload and register the images as AWS AMIs
+* Stable over time: convenient (read: doable) to add new versions (or old versions?)

example/Makefile

@@ -2,9 +2,13 @@ ROOT := $(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
 SCRIPTS ?= $(ROOT)/../scripts
 
 INTERCALATE ?= $(SCRIPTS)/intercalate
+INCLUDE ?= $(SCRIPTS)/include
 
-.PHONY: spec
-spec: openbsd.toml
+.PHONY: all
+all: openbsd.toml README.md
 
 openbsd.toml: $(wildcard parts/*.toml) | $(INTERCALATE)
 	$(INTERCALATE) $@ $^
+
+README.md: README.in.md $(wildcard parts/*.toml) | $(INCLUDE)
+	$(INCLUDE) $< $@

example/README.in.md

@@ -0,0 +1,41 @@
+# Example setup
+
+```toml
+@include "parts/00.toml"
+```
+
+```toml
+@include "parts/10.base.toml"
+```
+
+```toml
+@include "parts/20.site.toml"
+```
+
+```toml
+@include "parts/21.site.patch.doas.toml"
+```
+
+```toml
+@include "parts/22.site.patch.ntpd.toml"
+```
+
+```toml
+@include "parts/23.site.patch.nginx.toml"
+```
+
+```toml
+@include "parts/24.site.patch.echoip.toml"
+```
+
+```toml
+@include "parts/30.run.toml"
+```
+
+```toml
+@include "parts/40.aws.ami.toml"
+```
+
+```toml
+@include "parts/41.aws.terraform.toml"
+```

example/README.md

@@ -0,0 +1,87 @@
+# Example setup
+
+```toml
+app = "foo"
+version = "7.4"
+arch = "amd64"
+```
+
+```toml
+[base]
+disk.size = 4096
+sets = [ "man", "game", "comp" ]
+network.interface = "xnf0"
+sshd.port = 21230
+```
+
+```toml
+[site]
+pkgs = [ "awscli" ]
+timeout = 1800
+```
+
+```toml
+[[site.patch.doas.files]]
+lines = [ "permit nopass :wheel" ]
+mode = 0o400
+dst = "/etc/doas.conf"
+```
+
+```toml
+[[site.patch.ntpd.files]]
+dst = "/etc/ntpd.conf"
+lines = [
+  "server 169.254.169.123 weight 2", # https://aws.amazon.com/blogs/aws/keeping-time-with-amazon-time-sync-service/
+  "servers pool.ntp.org",
+  "sensor *",
+  "constraints from openbsd.org",
+]
+```
+
+```toml
+[site.patch.nginx]
+pkg = "nginx"
+service = "nginx"
+
+[[site.patch.nginx.files]]
+src = "site/index.html"
+dst = "/var/www/htdocs/index.html"
+
+[[site.patch.nginx.files]]
+src = "site/nginx.conf"
+dst = "/etc/nginx/nginx.conf"
+```
+
+```toml
+[site.patch.echoip]
+pkgs = [ "go" ]
+services = [ "echoip" ]
+install = "site/echoip/install"
+
+[[site.patch.echoip.files]]
+src = "site/echoip/service"
+mode = 0o755
+dst = "/etc/rc.d/echoip"
+```
+
+```toml
+[run]
+sshd.port = 21230
+
+[[run.hostfwd.tcp]]
+hport = 8000
+gport = 80
+```
+
+```toml
+[aws.ami]
+snapshot.s3.bucket = "rootmos-infra-artifacts"
+snapshot.s3.key_template = "uploads/%APP-%TIMESTAMP-%SALT.img"
+vmimport_role = "arn:aws:iam::676237474471:role/infra-vmimport"
+```
+
+```toml
+[aws.ami.terraform]
+local = "image"
+output = "terraform/openbsd.tf"
+```

example/openbsd.toml

@@ -6,6 +6,7 @@ arch = "amd64"
 disk.size = 4096
 sets = [ "man", "game", "comp" ]
 network.interface = "xnf0"
+sshd.port = 21230
 
 [site]
 pkgs = [ "awscli" ]
@@ -47,6 +48,9 @@ src = "site/echoip/service"
 mode = 0o755
 dst = "/etc/rc.d/echoip"
 
+[run]
+sshd.port = 21230
+
 [[run.hostfwd.tcp]]
 hport = 8000
 gport = 80

example/parts/10.base.toml

@@ -2,3 +2,4 @@
 disk.size = 4096
 sets = [ "man", "game", "comp" ]
 network.interface = "xnf0"
+sshd.port = 21230

example/parts/30.run.toml

@@ -1,3 +1,6 @@
+[run]
+sshd.port = 21230
+
 [[run.hostfwd.tcp]]
 hport = 8000
 gport = 80