vole

Clone

Read only, no credentials:

https://rodent.software/git/vole.git

Write over SSH with a registered key:

git clone ssh://git@0.0.0.0:2222/vole.git

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

Docs: rewrite the README and organize the guides

520470e19cd906bd6fff987e2d132d793ce56486 · Keenan Nemetz · 16d ago · parent c5902451

Docs: rewrite the README and organize the guides

Replace the long README with a landing page, split feature details into focused guides, and remove the roadmap and spike notes. Update comments that referenced them.

docs/getting-started.md +117

@@ -0,0 +1,117 @@
	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 or newer, to build Vole.
	10	- Git.
	11	- An SSH key. Vole uses the key to recognize you when you push. If you already use
	12	GitHub or another forge with SSH, you can reuse that key.
	13	- Optional: `git-lfs`, if you plan to store large files.
	14
	15	## Build Vole
	16
	17	From a source checkout:
	18
	19	```sh
	20	git clone <repository-url>
	21	cd vole
	22	go build -o vole ./cmd/vole
	23	```
	24
	25	Or build it directly:
	26
	27	```sh
	28	go build -o vole github.com/rodent-software/vole/cmd/vole
	29	```
	30
	31	## Create an instance
	32
	33	Pick a directory for the instance and run `vole init` there:
	34
	35	```sh
	36	mkdir forge
	37	cd forge
	38	/path/to/vole init --dir .
	39	```
	40
	41	Vole creates:
	42
	43	```text
	44	vole.toml settings
	45	data/users.db accounts, SSH keys, access rules, and locks
	46	data/repos/ your Git repositories
	47	data/audit.log a record of privileged actions
	48	```
	49
	50	`vole init` stores an absolute path in `vole.toml`, so you can start Vole from
	51	another directory later.
	52
	53	## Create an account and a repository
	54
	55	```sh
	56	vole user create you
	57	vole user add-key you --key ~/.ssh/id_ed25519.pub
	58	vole repo create demo --owner you
	59	```
	60
	61	An account cannot sign in until it has at least one key. The owner of a new
	62	repository is its first admin.
	63
	64	New repositories are private. To make the web page and anonymous clone URL
	65	readable, publish it:
	66
	67	```sh
	68	vole acl default demo read
	69	```
	70
	71	## Start Vole
	72
	73	```sh
	74	vole serve
	75	```
	76
	77	By default, Vole listens on:
	78
	79	- `127.0.0.1:2222` for SSH. This is how you write to repositories.
	80	- `127.0.0.1:8080` for the web interface and anonymous cloning. This side is
	81	read-only.
	82
	83	If you start Vole from another directory, point it at the config file:
	84
	85	```sh
	86	vole serve --config /srv/forge/vole.toml
	87	```
	88
	89	Most administrative commands also accept `--config`.
	90
	91	## Clone and push
	92
	93	```sh
	94	git clone ssh://git@127.0.0.1:2222/demo.git # read and write, using your key
	95	git clone http://127.0.0.1:8080/git/demo.git # read only, no credentials
	96	```
	97
	98	To check which account your key belongs to:
	99
	100	```sh
	101	cd demo
	102	vole whoami
	103	```
	104
	105	Try creating an issue:
	106
	107	```sh
	108	vole issue new --title "Docs are blank" -m "The index page renders nothing."
	109	```
	110
	111	## Where to go next
	112
	113	- [Configuration](configuration.md) — change addresses, limits, and the public URL.
	114	- [Users and access](users-and-access.md) — invite teammates and set permissions.
	115	- [CI](ci.md) — add a workflow and run your first build.
	116	- [Sites](sites.md) — publish a website from a repository.
	117	- [Operations](operations.md) — back up your instance.