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/sites.md +70

@@ -0,0 +1,70 @@
	1	# Sites
	2
	3	A website can be a branch. That keeps publishing simple and keeps the files with
	4	the project. Vole serves a repository's `pages` branch at `<repo>.<pages_domain>`.
	5	There is no build step on the server: change the branch and the next request sees
	6	the new files.
	7
	8	## Publish a build directory
	9
	10	Most websites are generated into a directory such as `dist/`. Vole can publish
	11	that directory as a snapshot, so the branch contains exactly those files. If you
	12	delete a page from the build, it stops being served.
	13
	14	```sh
	15	npm run build
	16	vole pages deploy dist # publish dist/ to the pages branch
	17	vole pages deploy dist --dry-run # show changes without pushing
	18	vole pages status # show the current branch and files
	19	vole pages unpublish # take the site down
	20	```
	21
	22	Publishing the same files twice does nothing. Use `--branch` if the instance
	23	serves a different branch than `pages`.
	24
	25	Dotfiles such as `.nojekyll` and `.well-known/` are published. Vole skips `.git`
	26	and symbolic links. A site is just files, and a link pointing outside the build
	27	directory would publish something you did not choose.
	28
	29	## Publish by hand
	30
	31	Plain Git is enough:
	32
	33	```sh
	34	git switch --orphan pages
	35	printf '<h1>hello</h1>\n' > index.html
	36	git add index.html
	37	git commit -m "site"
	38	git push origin pages # live at https://demo.pages.example.com/
	39	```
	40
	41	## Turn sites on
	42
	43	```toml
	44	pages_domain = "pages.example.com" # <repo>.pages.example.com
	45	pages_ref = "pages" # branch to serve
	46	pages_procs = 4 # Git reader processes per active site
	47	pages_cache_bytes = 33554432 # 32 MiB of cached files
	48	```
	49
	50	Set `pages_domain` to enable websites. If you change `pages_ref`, pass the same
	51	branch name to `vole pages deploy --branch`.
	52
	53	## How sites are served
	54
	55	- A directory serves its `index.html`. A directory URL without a trailing slash
	56	redirects to the version with one.
	57	- Vole uses the file's Git hash as its `ETag` and the commit time as
	58	`Last-Modified`, so unchanged pages return `304`.
	59	- Vole checks the branch and repository visibility once a second, so changes take
	60	effect within that window.
	61	- A private repository has no public website. There is no logged-in reader, so the
	62	site returns `404`, just like its clone URL.
	63
	64	Sites use subdomains of the instance's own domain, so they can share the
	65	certificate you already have. Terminate TLS in a proxy in front of `http_addr` and
	66	keep the `Host` header; it is how Vole knows which site was requested. See
	67	[Configuration § Running behind a proxy](configuration.md#running-behind-a-proxy).
	68
	69	A workflow can publish the site as its last step. See
	70	[CI § Publish a website in CI](ci.md#publish-a-website-in-ci).