collin/anvil

main / 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 in Docker the way it runs in production, `compose.override.yaml`
33	layers local settings over the deployment file and compose merges it
34	automatically:
35
36	```sh
37	docker compose up -d --build # then http://127.0.0.1:20640
38	docker compose logs -f
39	docker compose down
40	```
41
42	The override swaps in `deploy/anvil.dev.toml` (so agent sessions are on and the
43	SSO issuer is `https://login.localhost`), publishes to loopback instead of the
44	droplet's public IP, uses the `anvil-dev-data` volume, and mounts the Docker
45	socket that agent sessions need. `hag` passes `-f compose.yaml` explicitly, so
46	none of it reaches the host.
47
48	`./deploy/dev.sh` is the fuller path and still there: it also generates the
49	`deploy/dev-ca.crt` bundle the override mounts, waits for `/-/healthz`, and
50	points [portless](https://www.npmjs.com/package/portless) at the container for
51	`https://anvil.localhost`.
52
53	## Deploying
54
55	`compose.yaml` describes the deployment; `hag`, the shared deploy tool for
56	every project on hagrid, runs it there. `docker/Dockerfile` compiles anvild out
57	of the build context, so there is nothing to stage first:
58
59	```sh
60	hag deploy # build, push, then pull and recreate on the host
61	hag deploy -n # dry run: print every step, change nothing
62	hag status # what the host is running
63	hag logs -f # its logs
64	```
65
66	Full details, including first-run setup and the CD webhook, are in
67	[DEPLOY.md](DEPLOY.md).
68
69	## Docs
70
71	- [CI artifacts](docs/ci-artifacts.md)
72	- [Remote runners](docs/remote-runners.md) — dial-out runners so CI executes
73	off-box; design, not yet built
74	- [Single sign-on](docs/oidc.md) — OIDC sign-in, alongside passwords
75	- [Repository secrets](docs/secrets.md) — encrypted to your ssh keys in the
76	browser; anvil stores ciphertext it cannot open
77	- [Threat model for untrusted users](docs/untrusted-mode.md)