Getting started

This guide takes you from the source code to a repository you can clone. Vole is built to get out of the way: no sign-up, no external database, and no web server to configure. You can have a working forge in a few minutes.

What you need

• Go 1.27.3 or newer, to build Vole. go.mod pins that toolchain, so an older go on PATH fetches it on the first build instead of failing.
• A C compiler and the SQLite development headers: libsqlite3-dev on Debian and Ubuntu, sqlite-devel on Fedora and RHEL. Vole links SQLite dynamically, so the binary needs libsqlite3.so.0 on the machine that runs it; the packages install it for you. The library must be built with FTS5 (the distributions above enable it), which is what global search uses.
• Git.
• An SSH key. Vole uses the key to recognize you when you push. If you already use GitHub or another forge with SSH, you can reuse that key.
• Optional: git-lfs, if you plan to store large files.

Build Vole

From a source checkout:

git clone <repository-url>
cd vole
go build -tags libsqlite3,sqlite_fts5 -o vole ./cmd/vole

Or build it directly:

go build -tags libsqlite3,sqlite_fts5 -o vole rodent.software/vole/cmd/vole

Create an instance

Pick a directory for the instance and run vole admin init there:

mkdir forge
cd forge
/path/to/vole admin init --dir .

Vole creates:

vole.toml          settings
data/users.db      accounts, SSH keys, access rules, and locks
data/repos/        your Git repositories
data/audit.log     a record of privileged actions

vole admin init stores an absolute path in vole.toml, so you can start Vole from another directory later. If you initialise into ~/.vole, commands run from anywhere find that instance. For another location, pass --config or set VOLE_CONFIG (see Configuration).

Create an account and a repository

vole admin account create you --key ~/.ssh/id_ed25519.pub
vole admin repo create demo --owner you

Creating an account requires its first SSH key: the account and key are written together, so a name is never claimed by an account that cannot sign in. Use vole admin account add-key afterwards to attach more keys. The account name is permanent — a contribute account’s branches live under refs/heads/contrib/<name>/. The owner of a new repository is its first admin.

New repositories are private. To make the web page and anonymous clone URL readable, publish it:

vole admin acl set-default-role demo read

Once you have an instance admin, the same commands work from another machine with --remote. See Accounts and access.

Start Vole

vole serve

By default, Vole listens on:

• 127.0.0.1:2222 for SSH. This is how you push to repositories.
• 127.0.0.1:8080 for the web interface and anonymous cloning. The web serves reads to everyone and accepts passkey-authenticated issue, comment, and approval writes; Git over HTTP is read-only.

If you start Vole from another directory, point it at the config file:

vole serve --config /srv/forge/vole.toml

Most administrative commands also accept --config.

Clone and push

git clone ssh://git@127.0.0.1:2222/demo.git     # read and write, using your key
git clone http://127.0.0.1:8080/demo.git    # read only, no credentials

To check which account your key belongs to, and the role it holds on this repository:

cd demo
vole whoami
vole whoami --role

Try creating an issue:

vole issue new --title "Docs are blank" -m "The index page renders nothing."

Where to go next

• Configuration — change addresses, limits, and the public URL.
• Accounts and access — create accounts and set permissions.
• Workflows — add a workflow and run your first build.
• Runners — start a machine that executes the work.
• Sites — publish a website from a repository.
• Operations — back up your instance.