collin/anvil

f088bfe3205afcbd75b57c6e099baa0eff1efc1e / README.md

1	# anvil
2
3	A git forge built using [gitoxide](https://github.com/GitoxideLabs/gitoxide).
4
5	## Architecture
6
7	A Cargo workspace. The keystone is `anvil-git`: gix is a client library
8	with no server-side protocol, so anvil supplies its own transport-agnostic
9	`upload-pack`/`receive-pack` (smart-HTTP and SSH share one implementation).
10
11	\| Crate \| Responsibility \|
12	\|--------------\|----------------\|
13	\| `anvil-core` \| Domain model, SQLite persistence, on-disk bare-repo storage \|
14	\| `anvil-git` \| Server-side git wire protocol on gix (upstream-candidate) \|
15	\| `anvil-web` \| axum HTTP server: web UI + smart-HTTP git endpoints \|
16	\| `anvil-ssh` \| git-over-SSH (russh) \|
17	\| `anvil-cli` \| `anvild` daemon + admin CLI \|
18
19	## Quick start
20
21	```sh
22	cargo run -- migrate # create data/ + database
23	cargo run -- user create alice --password secret # create a user
24	cargo run -- repo create alice/hello # create a bare repo on disk
25	cargo run -- serve # start the server
26	```
27
28	Configuration is optional; see [`anvil.example.toml`](anvil.example.toml).
29	`PORT`/`HOST` and `ANVIL_BASE_URL` (or `PORTLESS_URL`) override the listen
30	address and public URL, so a proxy can place anvil without a config file.
31
32	To run it the way it runs in production — in Docker, with CI able to reach the
33	host's Docker socket — use `./deploy/dev.sh`, which builds the image, starts a
34	container, and (with [portless](https://www.npmjs.com/package/portless)) serves
35	it over HTTPS at `https://anvil.localhost`.
36
37	## Docs
38
39	- [CI artifacts](docs/ci-artifacts.md)
40	- [Single sign-on](docs/oidc.md) — OIDC sign-in, alongside passwords
41	- [Repository secrets](docs/secrets.md) — encrypted to your ssh keys in the
42	browser; anvil stores ciphertext it cannot open
43	- [Threat model for untrusted users](docs/untrusted-mode.md)