87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
# Werkator
|
|
|
|
Lightweight, declarative and highly opinionated software build system (CI/CD).
|
|
|
|
## Documentation
|
|
|
|
- [docs/configuration.md](docs/configuration.md) — configuration reference
|
|
- [docs/bootstrapping.md](docs/bootstrapping.md) — initializing a repository with `init`
|
|
- [docs/deployment.md](docs/deployment.md) — running Werkator as a systemd service behind a reverse proxy
|
|
|
|
## Adding a Gitea Repository
|
|
|
|
One instance serves several repositories (`docs/deployment.md`, ADR 0009).
|
|
From the workstation, clone and initialise, then register:
|
|
|
|
```bash
|
|
tools/remote --env-file .env.<instance> werkator repo-add https://gitea.example.org/<owner>/<repo>.git [<name>]
|
|
```
|
|
|
|
It prints the registry entry: add it to `~/.werkator.yml` under `repositories:`, then restart the service.
|
|
The optional `[<name>]` overrides the directory basename: it becomes the route segment (`/repos/<name>/…`) and the UI switcher entry, so it must be unique.
|
|
Needed only when the clone directory name is wrong or collides — e.g. `michael.hoennig.de.git` checked out as `michael.hoennig.de`, or two forges serving a repo of the same name.
|
|
A **public** repository needs nothing else: the clone runs anonymously.
|
|
A **private** repository needs shared credentials once on the host, in `~/.werkator.yml` of the service user, before cloning:
|
|
|
|
```yaml
|
|
defaults:
|
|
git:
|
|
account: <gitea-user>
|
|
token: <token> # Gitea → Settings → Applications → Generate Token, scope read:repository
|
|
```
|
|
|
|
## Developer Setup
|
|
|
|
Source `.envrc` to add `tools/` to your `PATH`, or install [direnv](#direnv) to have this done automatically on `cd`:
|
|
|
|
```bash
|
|
source .envrc
|
|
```
|
|
|
|
Common tasks:
|
|
|
|
```bash
|
|
./gradlew build # compile and run all checks
|
|
./gradlew test # run tests
|
|
./gradlew ktlintFormat # auto-format Kotlin sources
|
|
./gradlew ktlintCheck # check formatting (also runs as part of build)
|
|
|
|
adr-status # show all architecture decisions at a glance
|
|
```
|
|
|
|
|
|
|
|
### direnv
|
|
|
|
[direnv](https://direnv.net/) sources `.envrc` automatically whenever you enter the repository and unloads it when you leave.
|
|
|
|
```bash
|
|
# Ubuntu
|
|
sudo apt install direnv
|
|
|
|
# add to ~/.bashrc or ~/.zshrc
|
|
eval "$(direnv hook bash)" # or: eval "$(direnv hook zsh)"
|
|
```
|
|
|
|
Trust the project's `.envrc` once per clone:
|
|
|
|
```bash
|
|
direnv allow
|
|
```
|
|
|
|
### Tools (`tools/`)
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `adr-status` | List all Architecture Decision Records with their status and decision summary |
|
|
|
|
## Architecture Decision Records
|
|
|
|
Major technical decisions are documented as ADRs in [`docs/adrs/`](docs/adrs/).
|
|
|
|
```bash
|
|
adr-status # show all decisions at a glance
|
|
```
|
|
|
|
New ADRs follow the template at [`docs/adrs/0000-00-00.adr-template.md`](docs/adrs/0000-00-00.adr-template.md).
|