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/operations.md +83

@@ -0,0 +1,83 @@
	1	# Operations
	2
	3	A forge you own should be easy to back up and recover. Vole keeps the important
	4	state small: a user database, a handful of files, and ordinary Git repositories.
	5	These are the tasks that keep an instance healthy.
	6
	7	## Back up an instance
	8
	9	Back up three things:
	10
	11	```sh
	12	vole user backup backup/users.db # accounts, keys, access rules, locks
	13	cp data/ssh_host_ed25519_key backup/ # the only secret on the machine
	14	cp data/audit.log backup/ 2>/dev/null # history of admin actions
	15	```
	16
	17	`vole user backup` takes a consistent copy, even while Vole is running. Copying
	18	`users.db` by hand can miss recent changes that have not been written to the main
	19	database file yet.
	20
	21	If you lose the user database, you need to recreate accounts and add their keys
	22	again. You do not lose repositories. Nothing in the user database is secret, so a
	23	copied backup does not expose anything.
	24
	25	Repositories are ordinary Git repositories under `data/repos/`. You can back them
	26	up by copying or cloning. Issues, change requests, releases, and CI records travel
	27	with them because they are stored in Git.
	28
	29	## Restore an instance
	30
	31	1. Restore `data/users.db`, `data/ssh_host_ed25519_key`, and `data/audit.log`.
	32	2. Restore the repositories under `data/repos/`.
	33	3. Run `vole index rebuild`.
	34	4. Start `vole serve`.
	35
	36	Large files, CI logs, and build artifacts live in `data/lfs/`. Back that directory
	37	up too if you need those files. `vole gc` treats files reachable from a
	38	repository, an archived CI log, or a published artifact as things to keep.
	39
	40	## Clean up stored files
	41
	42	```sh
	43	vole gc --dry-run # show what would be removed
	44	vole gc # remove unused files
	45	vole gc --grace 24h # keep unused files for a day
	46	```
	47
	48	`vole gc` cleans the shared storage used by LFS, CI logs, and build artifacts. It
	49	also repairs each repository's links into that storage, so it helps when files
	50	are missing or links are broken.
	51
	52	The default grace period is one hour. A recent upload that has not been pushed yet
	53	will not be removed.
	54
	55	You can run `vole gc` while people are pushing. There is no need to schedule it;
	56	storage only grows when someone pushes files.
	57
	58	## Rebuild indexes
	59
	60	`data/index.db` is generated by Vole and can be deleted safely:
	61
	62	```sh
	63	vole index rebuild
	64	```
	65
	66	`data/runs.db` holds the CI queue and run index. Deleting it loses attempts that
	67	were in progress. Vole queues current branch and tag tips again from Git, and
	68	`vole index rebuild` restores finished history from the run records on each
	69	repository's `vole` branch.
	70
	71	## Security notes
	72
	73	- The SSH host key is the only secret Vole stores. Keep it readable only by the
	74	Vole user (`0600`).
	75	- Nothing Vole writes is signed: not pushes, not approvals, not CI results. Vole
	76	relies on the SSH key at the connection, the checks before a push is accepted,
	77	and the audit log.
	78	- The web interface is read-only. There is no password store, login, or session
	79	token.
	80	- Private repositories return `404` on the web and over HTTP, so visitors cannot
	81	confirm that they exist.
	82	- Vole does not handle TLS. Put it behind a proxy that terminates TLS and keeps
	83	the `Host` header, so site routing still works.