vole

Clone

Read only, no credentials:

https://rodent.software/git/vole.git

Write over SSH with a registered key:

git clone ssh://git@0.0.0.0:2222/vole.git

A free and open-source forge that lives in your Git repo.

Rewrite the deployment guides as console walkthroughs

942c93cd06345416c580176c1a149f98e7e96cc0 · Keenan Nemetz · 3d ago · parent 51624dc6

Rewrite the deployment guides as console walkthroughs

With the provider configurations gone, the guides are what is left, and
their shape changed: render a file, paste it into a console field, point a
name at the machine.

The index gains the section the Terraform version did not need — first boot
happens once. Editing the pasted file afterwards changes nothing, which is
how cloud-init works rather than a limitation of these pages, so a later
settings change is editing /etc/vole/vole.toml and restarting, and an
upgrade is a package install.

Each cloud page is a table of console fields: image, size, where the user
data goes, and a firewall. The firewall table is load-bearing rather than
advice, because Hetzner and DigitalOcean leave a new machine open and AWS
hands it a security group that allows nothing inbound.

The runner page leads with render.sh runner and keeps the by-hand path under
it; the registration commands are written out now that no output prints them.

docs/deploy/runner.md +21−39

@@ -1,44 +1,35 @@
	1	1	# CI runners
	2	2
	3	3	A runner is a machine that leases jobs from your instance over SSH, runs each job
	4		in a container, and reports the result. Vole does not build on the forge's own
	5		server: the machine that runs repository code is a machine you chose, with the OCI
	6		runtime you installed on it.
		4	in a container, and reports the result. It is a second machine, never the forge's
		5	own: it executes repository code and can read every secret its jobs declare, so it
		6	should not share a disk with the account database and the SSH host key.
	7	7
	8		The [deployment guides](README.md) can create one for you, or you can set one up
	9		on a machine you already have. Either way there is one step only an admin can do,
	10		and it is per repository.
		8	Give it its own machine the same way you created the forge — a rendered first-boot
		9	file pasted into the console — or set one up on a machine you already have. Either
		10	way there is one step only an admin can do, and it is per repository.
	11	11
	12		## Let the deployment create one
		12	## Create a runner machine
	13	13
	14		Each Terraform configuration takes `-var runner=true` and creates a second machine
	15		next to the forge: rootless Podman, an unprivileged `ci-runner` account, a pinned
	16		host key, and `vole-runner.service` enabled and waiting for work.
		14	Create a server the way the [Hetzner](hetzner.md), [DigitalOcean](digitalocean.md),
		15	or [AWS](aws.md) guide describes, with three differences: the runner's file instead
		16	of the forge's, no inbound ports except 22, and a disk sized for container images.
	17	17
	18	18	```sh
	19		cd deploy/terraform/hetzner
	20		terraform apply \
	21		-var domain=forge.example.com \
	22		-var runner=true \
	23		-var "admin_ssh_public_key=$(cat ~/.ssh/id_ed25519.pub)" \
	24		-var vole_package_url=https://example.com/r/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb
	25
	26		terraform output runner_setup
		19	cd deploy/cloud-init
		20	FORGE_HOST=forge.example.com \
		21	VOLE_PACKAGE_URL=https://example.com/r/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb \
		22	./render.sh runner > runner-user-data.yaml
	27	23	```
	28	24
	29		`runner_setup` prints the commands in the next section, filled in with the
	30		addresses this apply created.
	31
	32		\| Setting \| Default \| What it does \|
	33		\|---\|---\|---\|
	34		\| `runner` \| `false` \| Create the second machine \|
	35		\| `runner_type` \| same size as the forge \| Server type or droplet size. Builds want memory; raise this before the forge's own \|
	36		\| `runner_labels` \| `["linux"]` \| What this machine advertises. A job with `runs-on` only comes to a runner carrying every label it asks for \|
	37		\| `runner_network` \| `bridge` \| Whether a job that asks for a network gets one. A job that fetches dependencies needs this; `none` means such a job waits for another runner instead \|
	38		\| `runner_disk_gb` \| `40` \| AWS only. Container images and caches fill this, not the repositories \|
		25	`render.sh runner` also reads `RUNNER_LABEL_NAMES` (default `linux`),
		26	`RUNNER_NETWORK` (default `bridge`), `RUNNER_RUNTIME` (default `podman`), and
		27	`RUNNER_HOSTNAME`. The file installs the package, creates an unprivileged
		28	`ci-runner` account with the subordinate ids rootless Podman needs, generates the
		29	runner's key, pins the instance's host key once, and enables `vole-runner.service`.
	39	30
	40		The runner is not backed up. Its checkouts and caches are copies of what the
	41		repositories already have, and everything it produces is stored by the instance.
		31	If you would rather do it by hand on a machine that already exists, the steps are
		32	below.
	42	33
	43	34	## On a machine you already have
	44	35
@@ -46,15 +37,6 @@ A runner needs an OCI runtime — rootless Podman is preferred, because membersh
	46	37	in the Docker group is effectively root on the host — and it needs to reach the
	47	38	instance's SSH port.
	48	39
	49		```sh
	50		# Render the runner's first-boot file, then paste it into the provider's user
	51		# data field, or read it first and run the steps by hand.
	52		cd deploy/cloud-init
	53		FORGE_HOST=forge.example.com \
	54		VOLE_PACKAGE_URL=https://example.com/r/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb \
	55		./render.sh runner > runner-user-data.yaml
	56		```
	57
	58	40	On a machine you configure yourself, the package carries the unit, so it is three
	59	41	steps: install it, set up the account the runtime needs, and fill in the
	60	42	arguments.