Deploying Vole to a server

Vole is one binary, one configuration file, and one directory of state. It needs no database server, no cache, and no object store, so “deploying” means: get one small machine, install the package, say what address people will reach it on, and start it.

These pages do that for you. The machine configures itself on its first boot from a file you paste into the provider’s console — no Terraform, no API token, and nothing to install on your own computer except the shell you already have.

What you need

• A DNS name you can point at the machine, such as forge.example.com. Vole puts this in public_url, and browsers bind a passkey to that address, so pick the name you intend to keep.
• An SSH key. It becomes the first account, and it is how you push. Any key you already use with another forge works.
• A package file. Vole’s releases are published on its own instance, at rodent.software/vole/releases. Open the release you want and copy the URL of the file for your machine’s architecture: …/vole/releases/<tag>/artifacts/vole_<version>-1_amd64.deb, or arm64 instead of amd64.

There is no container image. Vole is one process whose state is a directory on local disk, so a container would add a layer without removing one, and it would cost the service unit’s hardening. If your machines are already managed by Compose or Kubernetes, give the forge a small virtual machine of its own; the first-boot file works there unchanged.

What happens on first boot

The machine installs the package, writes a configuration that answers on your name, creates the first account as an instance admin, and starts the service. That takes about two minutes.

Vole then obtains its own TLS certificate, so there is no proxy to configure. The certificate is requested the first time a browser arrives on the name, so the first visit after DNS starts answering can take a few seconds; if it fails, wait a minute and reload.

When it is up:

• https://forge.example.com is the forge.

• ssh://git@forge.example.com:2222/ is where repositories are cloned from.

• The account you created is an instance admin. It has no passkey yet, so the browser cannot sign it in until you issue one. From your laptop:

  vole admin --remote ssh://git@forge.example.com:2222 account invite admin
  

  Keep that link private: it is the one thing that grants browser access.

Your own shell access to the machine is on port 22 and stays useful for upgrades and backups. Vole’s Git over SSH is on port 2222 and is a separate listener.

First boot happens once

The file you paste configures the machine when it is created and then never again. Editing it afterwards changes nothing — that is how cloud-init works, not a limitation of these pages.

To change something later, edit the instance’s configuration and restart it:

sudo -e /etc/vole/vole.toml
sudo systemctl restart vole

To change something the first boot did — the account name, the TLS arrangement — create a new machine. That is cheap; the repositories come with a clone.

CI is a second machine

These guides create the forge. A runner — the machine that leases jobs and runs them in containers — is a separate decision and a separate machine, because it executes repository code and can read every secret a job declares.

• CI runners — creating one, registering it, and allowing it on a repository

Backups are still your job

A cloud’s daily snapshot is the fastest way to get a machine back after a bad upgrade, and it is not a backup of the instance. Two of Vole’s files must be kept apart from any copy of the data directory: the SSH host key that people’s clients pin, and secrets.key, which unseals repository secrets. A copy that holds both the data and that key is a copy of plaintext.

The procedure that covers this is short, and worth running once before you trust it:

• Operations § Back up an instance
• Operations § Restore an instance

Upgrading

The first boot is not configuration management. Upgrades are a package install on the machine:

• Packages § Upgrading

users.db is migrated in place the first time a newer binary reads it, and that migration cannot be undone, so take a backup first.

The files behind these guides

Everything the guides use lives under deploy/ in this repository: the two first-boot files and the renderer that fills them in. Read them before you run them; they are short.