Sign in

Search issue titles and bodies, change requests and comments. Private repositories you cannot read are not included.
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.

Blame · docs/getting-started.md

Line attribution on main · 134 line(s)

View file History
520470e1
Keenan Nemetz
16d ago
 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
536f08b9
Keenan Nemetz
13d ago
 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.
95425af7
Keenan Nemetz
10d ago
 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
41dd571f
Keenan Nemetz
10d ago
 14 install it for you. The library must be built with FTS5 (the distributions
1265ea55
Keenan Nemetz
9d ago
 15 above enable it), which is what global search uses.
520470e1
Keenan Nemetz
16d ago
 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
41dd571f
Keenan Nemetz
10d ago
 28 go build -tags libsqlite3,sqlite_fts5 -o vole ./cmd/vole
520470e1
Keenan Nemetz
16d ago
 29 ```
30
31 Or build it directly:
32
33 ```sh
d37d301f
Keenan Nemetz
18h ago
 34 go build -tags libsqlite3,sqlite_fts5 -o vole rodent.software/vole/cmd/vole
520470e1
Keenan Nemetz
16d ago
 35 ```
36
37 ## Create an instance
38
3abbe749
Keenan Nemetz
16d ago
 39 Pick a directory for the instance and run `vole admin init` there:
520470e1
Keenan Nemetz
16d ago
 40
41 ```sh
42 mkdir forge
43 cd forge
3abbe749
Keenan Nemetz
16d ago
 44 /path/to/vole admin init --dir .
520470e1
Keenan Nemetz
16d ago
 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
3abbe749
Keenan Nemetz
16d ago
 56 `vole admin init` stores an absolute path in `vole.toml`, so you can start Vole from
c36d5073
Keenan Nemetz
16d ago
 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)).
520470e1
Keenan Nemetz
16d ago
 60
61 ## Create an account and a repository
62
63 ```sh
2e024cc9
Keenan Nemetz
14d ago
 64 vole admin account create you --key ~/.ssh/id_ed25519.pub
3abbe749
Keenan Nemetz
16d ago
 65 vole admin repo create demo --owner you
520470e1
Keenan Nemetz
16d ago
 66 ```
67
c36d5073
Keenan Nemetz
16d ago
 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
2e024cc9
Keenan Nemetz
14d ago
 70 `vole admin account add-key` afterwards to attach more keys. The account name is
a781cd9b
Keenan Nemetz
6d ago
 71 permanent — a `contribute` account's branches live under
72 `refs/heads/contrib/<name>/`. The owner of a new repository is its first admin.
520470e1
Keenan Nemetz
16d ago
 73
74 New repositories are private. To make the web page and anonymous clone URL
75 readable, publish it:
76
77 ```sh
2e024cc9
Keenan Nemetz
14d ago
 78 vole admin acl set-default-role demo read
520470e1
Keenan Nemetz
16d ago
 79 ```
80
3abbe749
Keenan Nemetz
16d ago
 81 Once you have an instance admin, the same commands work from another machine
ab326d3a
Keenan Nemetz
14d ago
 82 with `--remote`. See [Accounts and access](accounts-and-access.md#remote-administration).
3abbe749
Keenan Nemetz
16d ago
 83
520470e1
Keenan Nemetz
16d ago
 84 ## Start Vole
85
86 ```sh
87 vole serve
88 ```
89
90 By default, Vole listens on:
91
6c84d387
Keenan Nemetz
16d ago
 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.
520470e1
Keenan Nemetz
16d ago
 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
b7396a11
Keenan Nemetz
6h ago
 109 git clone http://127.0.0.1:8080/demo.git # read only, no credentials
520470e1
Keenan Nemetz
16d ago
 110 ```
111
eec0e603
Keenan Nemetz
6d ago
 112 To check which account your key belongs to, and the role it holds on this
113 repository:
520470e1
Keenan Nemetz
16d ago
 114
115 ```sh
116 cd demo
117 vole whoami
eec0e603
Keenan Nemetz
6d ago
 118 vole whoami --role
520470e1
Keenan Nemetz
16d ago
 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.
ab326d3a
Keenan Nemetz
14d ago
 130 - [Accounts and access](accounts-and-access.md) — create accounts and set permissions.
70b70264
Keenan Nemetz
15d ago
 131 - [Workflows](workflows.md) — add a workflow and run your first build.
132 - [Runners](runner.md) — start a machine that executes the work.
520470e1
Keenan Nemetz
16d ago
 133 - [Sites](sites.md) — publish a website from a repository.
134 - [Operations](operations.md) — back up your instance.