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/README.md +25−17

@@ -5,21 +5,18 @@ no database server, no cache, and no object store, so "deploying" means: get one
	5	5	small machine, install the package, say what address people will reach it on, and
	6	6	start it.
	7	7
	8		These pages do that for you. Pick the way that matches the machine you have:
		8	These pages do that for you. The machine configures itself on its first boot from
		9	a file you paste into the provider's console — no Terraform, no API token, and
		10	nothing to install on your own computer except the shell you already have.
	9	11
	10	12	\| If you have… \| Start here \|
	11	13	\|---\|---\|
	12	14	\| A Hetzner Cloud account \| [Hetzner Cloud](hetzner.md) \|
	13	15	\| A DigitalOcean account \| [DigitalOcean](digitalocean.md) \|
	14	16	\| An AWS account \| [AWS](aws.md) \|
	15		\| Any Ubuntu or Debian machine, or a VPS provider not listed above \| [Any server](vps.md) \|
		17	\| Any other Ubuntu or Debian machine \| [Any server](vps.md) \|
	16	18	\| A container host \| [Docker](docker.md) \|
	17	19
	18		The three cloud guides use Terraform to create the machine, its firewall, its
	19		address, and — if the DNS lives with that cloud — the name that points at it. All
	20		of them use the same first-boot script to turn a fresh machine into an instance,
	21		so the result is the same wherever it runs.
	22
	23	20	## What you need
	24	21
	25	22	- A DNS name you can point at the machine, such as `forge.example.com`.
@@ -59,13 +56,27 @@ When it is up:
	59	56	Your own shell access to the machine is on port 22 and stays useful for upgrades
	60	57	and backups. Vole's Git over SSH is on port 2222 and is a separate listener.
	61	58
		59	## First boot happens once
		60
		61	The file you paste configures the machine when it is created and then never
		62	again. Editing it afterwards changes nothing — that is how cloud-init works, not a
		63	limitation of these pages.
		64
		65	To change something later, edit the instance's configuration and restart it:
		66
		67	```sh
		68	sudo -e /etc/vole/vole.toml
		69	sudo systemctl restart vole
		70	```
		71
		72	To change something the first boot did — the account name, the TLS arrangement —
		73	create a new machine. That is cheap; the repositories come with a clone.
		74
	62	75	## CI is a second machine
	63	76
	64	77	These guides create the forge. A runner — the machine that leases jobs and runs
	65	78	them in containers — is a separate decision and a separate machine, because it
	66		executes repository code and can read every secret a job declares. Each Terraform
	67		configuration takes `-var runner=true` to create one, and it needs one more step
	68		per repository before it takes work.
		79	executes repository code and can read every secret a job declares.
	69	80
	70	81	- [CI runners](runner.md) — creating one, registering it, and allowing it on a
	71	82	repository
@@ -86,11 +97,8 @@ it:
	86	97
	87	98	## Upgrading
	88	99
	89		These guides run once, at first boot. They are not configuration management:
	90		`terraform apply` again does not upgrade Vole, deliberately, because a machine
	91		holding a team's repositories should not be replaced by a plan.
	92
	93		To upgrade, install the new package on the machine:
		100	The first boot is not configuration management. Upgrades are a package install on
		101	the machine:
	94	102
	95	103	- [Packages § Upgrading](../packaging.md#upgrading)
	96	104
@@ -100,5 +108,5 @@ migration cannot be undone, so take a backup first.
	100	108	## The files behind these guides
	101	109
	102	110	Everything the guides use lives under [`deploy/`](../../deploy/README.md) in this
	103		repository: the first-boot script, the Terraform configurations, and the
	104		container files. Read them before you run them; they are short.
		111	repository: the first-boot file, the renderer that fills it in, and the container
		112	files. Read them before you run them; they are short.