vole

Clone

Read only, no credentials:

https://rodent.software/vole.git

Write over SSH with a registered key:

git clone ssh://git@rodent.software:2222/vole.git

A free and open-source forge that lives in your Git repo.

Code

395 commit(s) on main

Compare History

update readme Keenan Nemetz · 24m ago 32290114

source preview history blame raw 4.1 KiB

1	# Getting started
2
3	This guide takes you from the source code to a repository you can clone. Vole is
4	built to get out of the way: no sign-up, no external database, and no web server
5	to configure. You can have a working forge in a few minutes.
6
7	## What you need
8
9	- Go 1.27.3 or newer, to build Vole. `go.mod` pins that toolchain, so an older
10	`go` on `PATH` fetches it on the first build instead of failing.
11	- A C compiler and the SQLite development headers: `libsqlite3-dev` on Debian and
12	Ubuntu, `sqlite-devel` on Fedora and RHEL. Vole links SQLite dynamically, so
13	the binary needs `libsqlite3.so.0` on the machine that runs it; the packages
14	install it for you. The library must be built with FTS5 (the distributions
15	above enable it), which is what global search uses.
16	- Git.
17	- An SSH key. Vole uses the key to recognize you when you push. If you already use
18	GitHub or another forge with SSH, you can reuse that key.
19	- Optional: `git-lfs`, if you plan to store large files.
20
21	## Build Vole
22
23	From a source checkout:
24
25	```sh
26	git clone <repository-url>
27	cd vole
28	go build -tags libsqlite3,sqlite_fts5 -o vole ./cmd/vole
29	```
30
31	Or build it directly:
32
33	```sh
34	go build -tags libsqlite3,sqlite_fts5 -o vole rodent.software/vole/cmd/vole
35	```
36
37	## Create an instance
38
39	Pick a directory for the instance and run `vole admin init` there:
40
41	```sh
42	mkdir forge
43	cd forge
44	/path/to/vole admin init --dir .
45	```
46
47	Vole creates:
48
49	```text
50	vole.toml settings
51	data/users.db accounts, SSH keys, access rules, and locks
52	data/repos/ your Git repositories
53	data/audit.log a record of privileged actions
54	```
55
56	`vole admin init` stores an absolute path in `vole.toml`, so you can start Vole from
57	another directory later. If you initialise into `~/.vole`, commands run from
58	anywhere find that instance. For another location, pass `--config` or set
59	`VOLE_CONFIG` (see [Configuration](configuration.md#which-config-vole-reads)).
60
61	## Create an account and a repository
62
63	```sh
64	vole admin account create you --key ~/.ssh/id_ed25519.pub
65	vole admin repo create demo --owner you
66	```
67
68	Creating an account requires its first SSH key: the account and key are written
69	together, so a name is never claimed by an account that cannot sign in. Use
70	`vole admin account add-key` afterwards to attach more keys. The account name is
71	permanent — a `contribute` account's branches live under
72	`refs/heads/contrib/<name>/`. The owner of a new repository is its first admin.
73
74	New repositories are private. To make the web page and anonymous clone URL
75	readable, publish it:
76
77	```sh
78	vole admin acl set-default-role demo read
79	```
80
81	Once you have an instance admin, the same commands work from another machine
82	with `--remote`. See [Accounts and access](accounts-and-access.md#remote-administration).
83
84	## Start Vole
85
86	```sh
87	vole serve
88	```
89
90	By default, Vole listens on:
91
92	- `127.0.0.1:2222` for SSH. This is how you push to repositories.
93	- `127.0.0.1:8080` for the web interface and anonymous cloning. The web serves
94	reads to everyone and accepts passkey-authenticated issue, comment, and
95	approval writes; Git over HTTP is read-only.
96
97	If you start Vole from another directory, point it at the config file:
98
99	```sh
100	vole serve --config /srv/forge/vole.toml
101	```
102
103	Most administrative commands also accept `--config`.
104
105	## Clone and push
106
107	```sh
108	git clone ssh://git@127.0.0.1:2222/demo.git # read and write, using your key
109	git clone http://127.0.0.1:8080/demo.git # read only, no credentials
110	```
111
112	To check which account your key belongs to, and the role it holds on this
113	repository:
114
115	```sh
116	cd demo
117	vole whoami
118	vole whoami --role
119	```
120
121	Try creating an issue:
122
123	```sh
124	vole issue new --title "Docs are blank" -m "The index page renders nothing."
125	```
126
127	## Where to go next
128
129	- [Configuration](configuration.md) — change addresses, limits, and the public URL.
130	- [Accounts and access](accounts-and-access.md) — create accounts and set permissions.
131	- [Workflows](workflows.md) — add a workflow and run your first build.
132	- [Runners](runner.md) — start a machine that executes the work.
133	- [Sites](sites.md) — publish a website from a repository.
134	- [Operations](operations.md) — back up your instance.
135