collin/anvil

6ba1be4c75f32951328adf6d017dec45c3eee18f / 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	## Deploying
38
39	`compose.yaml` describes the deployment; `hag`, the shared deploy tool for
40	every project on hagrid, runs it there. The image carries a prebuilt static
41	binary rather than compiling in Docker, so one step comes first:
42
43	```sh
44	./deploy/deploy.sh # cross-compile, build, push, then restart on the host
45	./deploy/deploy.sh -n # dry run: print every step, change nothing
46	hag status # what the host is running
47	hag logs -f # its logs
48	```
49
50	Full details, including first-run setup and the CD webhook, are in
51	[DEPLOY.md](DEPLOY.md).
52
53	## Docs
54
55	- [CI artifacts](docs/ci-artifacts.md)
56	- [Remote runners](docs/remote-runners.md) — dial-out runners so CI executes
57	off-box; design, not yet built
58	- [Single sign-on](docs/oidc.md) — OIDC sign-in, alongside passwords
59	- [Repository secrets](docs/secrets.md) — encrypted to your ssh keys in the
60	browser; anvil stores ciphertext it cannot open
61	- [Threat model for untrusted users](docs/untrusted-mode.md)