mhoennigandClaude Opus 5
35f06ec1ec
`gitTally` is the name of another product in the git space, so the rename is a precaution; nothing about what the build system does changes. The name follows one rule: `Werkator` where it is prose, capitalized where it is a Kotlin type and its file, lowercase everywhere a machine reads it — the command, packages, paths, configuration keys and values, the Gitea check context. Environment variables keep their convention and are uppercase throughout. Every configuration file is still found under its pre-rename name (`ConfigFiles`): `.gittally.yml` at the repository root, in a build worktree and as committed on a branch, `.git/gittally/.gittally.yml` for the machine layer. The current name wins where both exist, and the old file is then ignored rather than merged — two files side by side are a half-done rename, not a layering. Without the fallback an installation that updated without renaming would not fail: a configuration that is not found leaves every setting at its default, so it would come up looking healthy while having forgotten its credentials and its builds. `docs/werkator-migrationsplan.md` lists what the fallback does not cover and has to be moved by hand — above all the state directory `.git/werkator/`, which holds the build history, the control token and the worktrees, and has no fallback of its own. `docs/migration-from-legacy.md` is deleted with this: it mapped the legacy script's environment variables, and every host it addressed has long since moved to the YAML configuration. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.7 KiB
Optional Managed nginx/TLS Container
Status:
- proposed: 2026-07-07
- accepted: 2026-07-07
- rejected: -
- superseded: -
Decision [accepted]: Werkator optionally manages an nginx+certbot Docker container for hosts without a usable reverse proxy — revises the "no managed nginx" part of ADR 0004; deployment behind an existing reverse proxy stays the default.
Context and Problem Statement
ADR 0004 dropped the legacy nginx/Let's Encrypt container management and documented deployment behind an existing reverse proxy instead. That decision was carried over from the rewrite plan without validating it against the primary target environment.
Technical Background
Werkator must run on Hostsharing managed container environments. These hosts provide Docker but no root access and no host web server that Werkator could sit behind. Without the managed nginx container, Werkator cannot be served over HTTPS there at all. The legacy script already solved this: it wrote an nginx config, ran an nginx Docker container, and obtained/renewed Let's Encrypt certificates via a certbot container in webroot mode.
Considered Options
- Keep ADR 0004 as is (host reverse proxy only)
- Re-add the legacy managed nginx+certbot container as an opt-in feature
- External tooling (user-maintained compose stack next to Werkator)
Host reverse proxy only
Advantages
- No container lifecycle or certificate code in werkator.
Disadvantages
- Unusable on Hostsharing container hosts — the primary deployment target.
Opt-in managed nginx+certbot container
Werkator starts and supervises a labelled nginx container and handles certificate issuance/renewal via certbot, only when explicitly enabled in the config.
Advantages
- Works on hosts that provide only Docker; HTTPS without root or a host web server.
- The behavior is proven — it is a port of the working legacy subsystem.
- Opt-in: hosts with a reverse proxy keep the simple ADR 0004 setup.
Disadvantages
- Re-adds container lifecycle and certificate renewal complexity to werkator.
External compose stack
Advantages
- Keeps Werkator itself simple.
Disadvantages
- Pushes nginx config templating, cert bootstrap ordering, and renewal onto every operator; exactly the manual work the legacy script automated.
Decision Outcome
Re-add the managed nginx+certbot container as an opt-in feature (docs/plan/13-nginx-tls.md).
This partially supersedes ADR 0004: its persistence and UI decisions stay in force; "no managed nginx/TLS" becomes "no managed nginx/TLS by default".
The reverse-proxy deployment from docs/deployment.md remains the recommended setup where a host web server exists.