Development

Build and test

go build ./cmd/ermite
go test ./...

go test ./... includes the end-to-end tests of internal/app (a real server per test). Run them before opening a pull request: CI runs them on main only.

Stamp the version with -ldflags "-X bnema.dev/ermite/internal/app.stamped=<version>".

Dev server

docker compose up        # http://localhost:7341
docker compose down -v   # also removes data and caches

The source is mounted and air rebuilds on each change to .go, .templ or web assets. The admin token is in compose.yaml. The container runs as root, which maps to your user under rootless Docker.

Docker image

docker build --build-arg VERSION="$(git describe --tags --always --dirty)" -t ermite .

Alpine with git, runs as uid 10001, data in /data. Behind a private route, --build-arg GIT_REWRITE_BASE=<url> rewrites the git host of the bnema.dev/ermite-* modules.

Tools

Pinned in go.mod:

go tool buf lint
go tool buf generate        # proto/ -> gen/
go generate ./...           # mockery mocks of the ports
go tool hexcheck -fail-on warn ./...

Architecture

cmd/ermite → internal/app → internal/usecase → internal/ports → internal/domain
                         ↘ internal/adapters (Git, KV, HTTP, API, web, client)

internal/app: CLI and composition root.
internal/usecase imports only domain and ports.
Adapters import domain, ports and internal/clientlimit; never a use case, app or another adapter.
The web adapter calls use cases through ports, never the generated API code.
internal/ports imports only domain; domain imports nothing from the module.
internal/config is used by internal/app only.

internal/boundary/boundary_test.go enforces the imports; hexcheck (.hexcheck.yaml) checks the layering.

source

1# Development
2
3## Build and test
4
5```sh
6go build ./cmd/ermite
7go test ./...
8```
9
10`go test ./...` includes the end-to-end tests of `internal/app` (a real server per test). Run them before opening a pull request: CI runs them on `main` only.
11
12Stamp the version with `-ldflags "-X bnema.dev/ermite/internal/app.stamped=<version>"`.
13
14## Dev server
15
16```sh
17docker compose up        # http://localhost:7341
18docker compose down -v   # also removes data and caches
19```
20
21The source is mounted and [air](https://github.com/air-verse/air) rebuilds on each change to `.go`, `.templ` or web assets. The admin token is in `compose.yaml`. The container runs as root, which maps to your user under rootless Docker.
22
23## Docker image
24
25```sh
26docker build --build-arg VERSION="$(git describe --tags --always --dirty)" -t ermite .
27```
28
29Alpine with git, runs as uid 10001, data in `/data`. Behind a private route, `--build-arg GIT_REWRITE_BASE=<url>` rewrites the git host of the `bnema.dev/ermite-*` modules.
30
31## Tools
32
33Pinned in `go.mod`:
34
35```sh
36go tool buf lint
37go tool buf generate        # proto/ -> gen/
38go generate ./...           # mockery mocks of the ports
39go tool hexcheck -fail-on warn ./...
40```
41
42## Architecture
43
44```
45cmd/ermite → internal/app → internal/usecase → internal/ports → internal/domain
46                         ↘ internal/adapters (Git, KV, HTTP, API, web, client)
47```
48
49- `internal/app`: CLI and composition root.
50- `internal/usecase` imports only `domain` and `ports`.
51- Adapters import `domain`, `ports` and `internal/clientlimit`; never a use case, `app` or another adapter.
52- The web adapter calls use cases through `ports`, never the generated API code.
53- `internal/ports` imports only `domain`; `domain` imports nothing from the module.
54- `internal/config` is used by `internal/app` only.
55
56`internal/boundary/boundary_test.go` enforces the imports; `hexcheck` (`.hexcheck.yaml`) checks the layering.

development.md RawHistoryFolder