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.

Document deploying to a server, one guide per path

b8e7a5679847cf4cdda0754f6154805585e1be96 · Keenan Nemetz · 3d ago · parent b86148d1

Document deploying to a server, one guide per path

The guides are for someone who has a machine and a domain and has not
deployed a forge before, so they start from what to have ready and end at a
working https address with one instance admin.

Each ends with the same three things: where first-boot output is, what a
certificate warning means, and that pushing needs port 2222 reachable and a
key that belongs to an account.

The index page carries what the per-cloud pages should not repeat: backups
are separate from a cloud snapshot because secrets.key must not travel with
the data, and upgrades are a package install rather than an apply.

docs/deploy/vps.md +121

@@ -0,0 +1,121 @@
	1	# Vole on any server
	2
	3	The cloud guides each create a machine for you. This page is for the machine you
	4	already have: a VPS from a provider without a Terraform guide, a spare server, or
	5	a virtual machine on your own hardware.
	6
	7	There are two ways, and the first one is less work.
	8
	9	## A machine that accepts user data
	10
	11	Most providers — Vultr, Linode, Scaleway, OVH, UpCloud, Proxmox, and others — let
	12	you paste "user data", "cloud-init", or a "startup script" into the form that
	13	creates a machine. Give it the rendered first-boot file and the machine configures
	14	itself.
	15
	16	Render it on your own computer. Pick `ubuntu-24.04` or `debian-13` as the image in
	17	the provider's form, and a size with 2 GB of memory and 20 GB of disk.
	18
	19	```sh
	20	cd deploy/cloud-init
	21
	22	HOSTNAME=forge.example.com \
	23	ADMIN_ACCOUNT=admin \
	24	ADMIN_EMAIL=you@example.com \
	25	ADMIN_SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)" \
	26	VOLE_PACKAGE_URL=https://example.com/r/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb \
	27	./render.sh > user-data.yaml
	28	```
	29
	30	Paste the contents of `user-data.yaml` into the provider's field and create the
	31	machine. The values are:
	32
	33	\| Variable \| What it is \|
	34	\|---\|---\|
	35	\| `HOSTNAME` \| The name people will reach the forge on. It becomes `public_url`, and passkeys bind to it, so choose the one you intend to keep \|
	36	\| `ADMIN_ACCOUNT` \| Name of the first account, made an instance admin. Account names are permanent \|
	37	\| `ADMIN_SSH_KEY` \| Public key of that account, as in the contents of `~/.ssh/id_ed25519.pub` \|
	38	\| `VOLE_PACKAGE_URL` \| The `.deb` for the machine's architecture \|
	39	\| `ADMIN_EMAIL` \| Contact address for the certificate authority. Optional, but a good idea \|
	40	\| `INSTANCE_NAME` \| What the landing page calls this forge. Default `Vole` \|
	41	\| `TLS_MODE` \| `acme` (the default) lets Vole obtain its own certificate. `proxy` leaves TLS to a proxy you run, and serves plain HTTP on loopback \|
	42
	43	Point the name at the machine's address, then open `https://forge.example.com`.
	44	The certificate is issued on the first visit after DNS answers, so a first attempt
	45	that fails is usually just early; wait a minute and reload.
	46
	47	`render.sh` needs `envsubst`, which is in `gettext-base` on Debian and Ubuntu or
	48	`gettext` elsewhere. Without it, edit `deploy/cloud-init/vole.yaml` by hand: each
	49	placeholder is a value with the same name.
	50
	51	To issue the first passkey for the admin account, run this from your laptop:
	52
	53	```sh
	54	vole admin --remote ssh://git@forge.example.com:2222 account invite admin
	55	```
	56
	57	## A machine you configure yourself
	58
	59	If the machine is already running and you have shell access, install the package
	60	and point it at your name. This is the same result the first-boot script
	61	produces, done by hand.
	62
	63	```sh
	64	# On the machine, as a user with sudo.
	65	curl -fsSLO https://example.com/r/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb
	66	sudo apt install ./vole_0.2.0-1_amd64.deb
	67	```
	68
	69	The package creates the `vole` service account, `/var/lib/vole`, and an instance
	70	under the shipped configuration. Now write the configuration people will reach:
	71
	72	```toml
	73	# /etc/vole/vole.toml
	74	data_dir = "/var/lib/vole/data"
	75
	76	http_addr = ":80"
	77	https_addr = ":443"
	78	public_url = "https://forge.example.com"
	79	acme_email = "you@example.com"
	80
	81	ssh_addr = "0.0.0.0:2222"
	82	```
	83
	84	Ports 80 and 443 are below 1024, and the packaged unit drops every capability, so
	85	grant the one that binds them:
	86
	87	```sh
	88	sudo install -d -m 0755 /etc/systemd/system/vole.service.d
	89	sudo tee /etc/systemd/system/vole.service.d/bind.conf >/dev/null <<'EOF'
	90	[Service]
	91	CapabilityBoundingSet=CAP_NET_BIND_SERVICE
	92	AmbientCapabilities=CAP_NET_BIND_SERVICE
	93	EOF
	94	```
	95
	96	Then create the first account and start the service:
	97
	98	```sh
	99	sudo systemctl daemon-reload
	100	sudo -u vole vole admin --config /etc/vole/vole.toml \
	101	account create admin --key /tmp/your-key.pub --role admin
	102	sudo systemctl enable --now vole
	103	```
	104
	105	`--role admin` is what makes this account an instance admin. The first one has to
	106	be granted on the host; after that, admins can manage the instance over SSH with
	107	`vole admin --remote`.
	108
	109	If you would rather run a proxy than let Vole hold the certificate, leave
	110	`https_addr` empty, set `http_addr = "127.0.0.1:8080"`, and name the header your
	111	proxy sets with the client address:
	112
	113	```toml
	114	git_http_client_ip_header = "X-Forwarded-For"
	115	```
	116
	117	## Then
	118
	119	- [Deploying Vole](README.md) — backups, upgrades, and what first boot does
	120	- [Packages](../packaging.md) — what the package installs, and how upgrades work
	121	- [Configuration](../configuration.md) — every setting, including limits and sites