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/README.md +93

@@ -0,0 +1,93 @@
	1	# Deploying Vole to a server
	2
	3	Vole is one binary, one configuration file, and one directory of state. It needs
	4	no database server, no cache, and no object store, so "deploying" means: get one
	5	small machine, install the package, say what address people will reach it on, and
	6	start it.
	7
	8	These pages do that for you. Pick the way that matches the machine you have:
	9
	10	\| If you have… \| Start here \|
	11	\|---\|---\|
	12	\| A Hetzner Cloud account \| [Hetzner Cloud](hetzner.md) \|
	13	\| A DigitalOcean account \| [DigitalOcean](digitalocean.md) \|
	14	\| An AWS account \| [AWS](aws.md) \|
	15	\| Any Ubuntu or Debian machine, or a VPS provider not listed above \| [Any server](vps.md) \|
	16	\| A container host \| [Docker](docker.md) \|
	17
	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	## What you need
	24
	25	- A DNS name you can point at the machine, such as `forge.example.com`.
	26	Vole puts this in `public_url`, and browsers bind a passkey to that address, so
	27	pick the name you intend to keep.
	28	- An SSH key. It becomes the first account, and it is how you push. Any key
	29	you already use with another forge works.
	30	- A package file. Vole is distributed as a `.deb` (and `.rpm`) attached to a
	31	release. Copy the URL of the file for your machine's architecture: recent
	32	releases are `…/releases/<tag>/artifacts/vole_<version>-1_amd64.deb`, or
	33	`arm64` instead of `amd64`.
	34
	35	## What happens on first boot
	36
	37	The machine installs the package, writes a configuration that answers on your
	38	name, creates the first account as an instance admin, and starts the service.
	39	That takes about two minutes.
	40
	41	Vole then obtains its own TLS certificate, so there is no proxy to configure. The
	42	certificate is requested the first time a browser arrives on the name, so the
	43	first visit after DNS starts answering can take a few seconds; if it fails, wait a
	44	minute and reload.
	45
	46	When it is up:
	47
	48	- `https://forge.example.com` is the forge.
	49	- `ssh://git@forge.example.com:2222/` is where repositories are cloned from.
	50	- The account you created is an instance admin. It has no passkey yet, so the
	51	browser cannot sign it in until you issue one. From your laptop:
	52
	53	```sh
	54	vole admin --remote ssh://git@forge.example.com:2222 account invite admin
	55	```
	56
	57	Keep that link private: it is the one thing that grants browser access.
	58
	59	Your own shell access to the machine is on port 22 and stays useful for upgrades
	60	and backups. Vole's Git over SSH is on port 2222 and is a separate listener.
	61
	62	## Backups are still your job
	63
	64	A cloud's daily snapshot is the fastest way to get a machine back after a bad
	65	upgrade, and it is not a backup of the instance. Two of Vole's files must be kept
	66	apart from any copy of the data directory: the SSH host key that people's clients
	67	pin, and `secrets.key`, which unseals repository secrets. A copy that holds both
	68	the data and that key is a copy of plaintext.
	69
	70	The procedure that covers this is short, and worth running once before you trust
	71	it:
	72
	73	- [Operations § Back up an instance](../operations.md#back-up-an-instance)
	74	- [Operations § Restore an instance](../operations.md#restore-an-instance)
	75
	76	## Upgrading
	77
	78	These guides run once, at first boot. They are not configuration management:
	79	`terraform apply` again does not upgrade Vole, deliberately, because a machine
	80	holding a team's repositories should not be replaced by a plan.
	81
	82	To upgrade, install the new package on the machine:
	83
	84	- [Packages § Upgrading](../packaging.md#upgrading)
	85
	86	`users.db` is migrated in place the first time a newer binary reads it, and that
	87	migration cannot be undone, so take a backup first.
	88
	89	## The files behind these guides
	90
	91	Everything the guides use lives under [`deploy/`](../../deploy/README.md) in this
	92	repository: the first-boot script, the Terraform configurations, and the
	93	container files. Read them before you run them; they are short.