Vole on any server

This page is for a provider without its own guide — Vultr, Linode, Scaleway, OVH, UpCloud, Proxmox — and for the machine you already have: a spare server, or a virtual machine on your own hardware. The first-boot file is the same one the Hetzner, DigitalOcean, and AWS guides paste into their consoles.

There are two ways, and the first one is less work.

A machine that accepts user data

Most providers let you paste “user data”, “cloud-init”, or a “startup script” into the form that creates a machine. Give it the rendered first-boot file and the machine configures itself.

Render it on your own computer. Pick ubuntu-24.04 or debian-13 as the image in the provider’s form, and a size with 2 GB of memory and 20 GB of disk.

cd deploy/cloud-init

HOSTNAME=forge.example.com \
ADMIN_ACCOUNT=admin \
ADMIN_EMAIL=you@example.com \
ADMIN_SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)" \
VOLE_PACKAGE_URL=https://rodent.software/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb \
  ./render.sh > user-data.yaml

Paste the contents of user-data.yaml into the provider’s field and create the machine. The values are:

Point the name at the machine’s address, then open https://forge.example.com. The certificate is issued on the first visit after DNS answers, so a first attempt that fails is usually just early; wait a minute and reload.

render.sh needs envsubst, which is in gettext-base on Debian and Ubuntu or gettext elsewhere. Without it, edit deploy/cloud-init/vole.yaml by hand: each placeholder is a value with the same name.

To issue the first passkey for the admin account, run this from your laptop:

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

A machine you configure yourself

If the machine is already running and you have shell access, install the package and point it at your name. This is the same result the first-boot script produces, done by hand.

# On the machine, as a user with sudo.
curl -fsSLO https://rodent.software/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb
sudo apt install ./vole_0.2.0-1_amd64.deb

The package creates the vole service account, /var/lib/vole, and an instance under the shipped configuration. Now write the configuration people will reach:

# /etc/vole/vole.toml
data_dir = "/var/lib/vole/data"

http_addr  = ":80"
https_addr = ":443"
public_url = "https://forge.example.com"
acme_email = "you@example.com"

ssh_addr = "0.0.0.0:2222"

Ports 80 and 443 are below 1024, and the packaged unit drops every capability, so grant the one that binds them:

sudo install -d -m 0755 /etc/systemd/system/vole.service.d
sudo tee /etc/systemd/system/vole.service.d/bind.conf >/dev/null <<'EOF'
[Service]
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
EOF

Then create the first account and start the service:

sudo systemctl daemon-reload
sudo -u vole vole admin --config /etc/vole/vole.toml \
  account create admin --key /tmp/your-key.pub --role admin
sudo systemctl enable --now vole

--role admin is what makes this account an instance admin. The first one has to be granted on the host; after that, admins can manage the instance over SSH with vole admin --remote.

If you would rather run a proxy than let Vole hold the certificate, leave https_addr empty, set http_addr = "127.0.0.1:8080", and name the header your proxy sets with the client address:

git_http_client_ip_header = "X-Forwarded-For"

Then

• Deploying Vole — backups, upgrades, and what first boot does
• Packages — what the package installs, and how upgrades work
• Configuration — every setting, including limits and sites