docs: document ermite serve and its environment
- commit
- b7fa16d51ebdf1eb96100e87c0c4650a560d0e66
- author
- brice · · 2026-10-10 06:17 UTC
- parent
- 251be53
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +35 -1
M README.md +35 -1
| @@ -2,7 +2,30 @@ | |||
| 2 | 2 | ||
| 3 | 3 | A single-user Git forge in one Go binary. ermite hosts bare repositories, serves clone and push over HTTPS, and shows them in a read-only web interface. | |
| 4 | 4 | ||
| 5 | - | Status: early development, not usable yet. | |
| 5 | + | Status: early development, not usable yet. `ermite serve` starts, opens its metadata store, reconciles the repositories on disk and answers `GET /-/health`. | |
| 6 | + | ||
| 7 | + | ## Run | |
| 8 | + | ||
| 9 | + | ```sh | |
| 10 | + | export ERMITE_DATA_DIR=/var/lib/ermite | |
| 11 | + | export ERMITE_PUBLIC_URL=https://git.example.com | |
| 12 | + | export ERMITE_ADMIN_TOKEN=$(head -c 32 /dev/urandom | base64) | |
| 13 | + | ermite serve | |
| 14 | + | ``` | |
| 15 | + | ||
| 16 | + | | Variable | Default | Notes | | |
| 17 | + | |---|---|---| | |
| 18 | + | | `ERMITE_DATA_DIR` | required | absolute path of the data root | | |
| 19 | + | | `ERMITE_PUBLIC_URL` | required | `http(s)` base URL, no path | | |
| 20 | + | | `ERMITE_ADMIN_TOKEN` | required | at least 32 characters | | |
| 21 | + | | `ERMITE_ADDR` | `:7341` | listen address | | |
| 22 | + | | `ERMITE_TRUSTED_PROXIES` | empty | comma-separated CIDRs | | |
| 23 | + | | `ERMITE_GIT` | `git` | git 2.45 or newer | | |
| 24 | + | | `ERMITE_SOURCE_URL` | `$ERMITE_PUBLIC_URL/ermite` | link to the source (AGPL) | | |
| 25 | + | | `ERMITE_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error` | | |
| 26 | + | | `ERMITE_LOG_FORMAT` | `json` | `json` or `console` | | |
| 27 | + | ||
| 28 | + | `ermite version` prints the version. | |
| 6 | 29 | ||
| 7 | 30 | ## Build | |
| 8 | 31 | ||
| @@ -11,6 +34,17 @@ go build ./cmd/ermite | |||
| 11 | 34 | go test ./... | |
| 12 | 35 | ``` | |
| 13 | 36 | ||
| 37 | + | ## Develop | |
| 38 | + | ||
| 39 | + | Tools are pinned in `go.mod`: | |
| 40 | + | ||
| 41 | + | ```sh | |
| 42 | + | go tool buf lint | |
| 43 | + | go tool buf generate # proto/ -> gen/ | |
| 44 | + | go generate ./... # mockery mocks of the ports | |
| 45 | + | go tool hexcheck -fail-on warn ./... | |
| 46 | + | ``` | |
| 47 | + | ||
| 14 | 48 | ## License | |
| 15 | 49 | ||
| 16 | 50 | AGPL-3.0-or-later. See [LICENSE](LICENSE). | |
| @@ -2,7 +2,30 @@ | |||||
| 2 | 2 | ||||
| 3 | A single-user Git forge in one Go binary. ermite hosts bare repositories, serves clone and push over HTTPS, and shows them in a read-only web interface. | 3 | A single-user Git forge in one Go binary. ermite hosts bare repositories, serves clone and push over HTTPS, and shows them in a read-only web interface. | ||
| 4 | 4 | ||||
| 5 | - | Status: early development, not usable yet. | 5 | + | Status: early development, not usable yet. `ermite serve` starts, opens its metadata store, reconciles the repositories on disk and answers `GET /-/health`. |
| 6 | + | ||||
| 7 | + | ## Run | |||
| 8 | + | ||||
| 9 | + | ```sh | |||
| 10 | + | export ERMITE_DATA_DIR=/var/lib/ermite | |||
| 11 | + | export ERMITE_PUBLIC_URL=https://git.example.com | |||
| 12 | + | export ERMITE_ADMIN_TOKEN=$(head -c 32 /dev/urandom | base64) | |||
| 13 | + | ermite serve | |||
| 14 | + | ``` | |||
| 15 | + | ||||
| 16 | + | | Variable | Default | Notes | | |||
| 17 | + | |---|---|---| | |||
| 18 | + | | `ERMITE_DATA_DIR` | required | absolute path of the data root | | |||
| 19 | + | | `ERMITE_PUBLIC_URL` | required | `http(s)` base URL, no path | | |||
| 20 | + | | `ERMITE_ADMIN_TOKEN` | required | at least 32 characters | | |||
| 21 | + | | `ERMITE_ADDR` | `:7341` | listen address | | |||
| 22 | + | | `ERMITE_TRUSTED_PROXIES` | empty | comma-separated CIDRs | | |||
| 23 | + | | `ERMITE_GIT` | `git` | git 2.45 or newer | | |||
| 24 | + | | `ERMITE_SOURCE_URL` | `$ERMITE_PUBLIC_URL/ermite` | link to the source (AGPL) | | |||
| 25 | + | | `ERMITE_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error` | | |||
| 26 | + | | `ERMITE_LOG_FORMAT` | `json` | `json` or `console` | | |||
| 27 | + | ||||
| 28 | + | `ermite version` prints the version. | |||
| 6 | 29 | ||||
| 7 | ## Build | 30 | ## Build | ||
| 8 | 31 | ||||
| @@ -11,6 +34,17 @@ go build ./cmd/ermite | |||||
| 11 | go test ./... | 34 | go test ./... | ||
| 12 | ``` | 35 | ``` | ||
| 13 | 36 | ||||
| 37 | + | ## Develop | |||
| 38 | + | ||||
| 39 | + | Tools are pinned in `go.mod`: | |||
| 40 | + | ||||
| 41 | + | ```sh | |||
| 42 | + | go tool buf lint | |||
| 43 | + | go tool buf generate # proto/ -> gen/ | |||
| 44 | + | go generate ./... # mockery mocks of the ports | |||
| 45 | + | go tool hexcheck -fail-on warn ./... | |||
| 46 | + | ``` | |||
| 47 | + | ||||
| 14 | ## License | 48 | ## License | ||
| 15 | 49 | ||||
| 16 | AGPL-3.0-or-later. See [LICENSE](LICENSE). | 50 | AGPL-3.0-or-later. See [LICENSE](LICENSE). | ||