added ADR 0005 and step 13: reintroduce managed nginx+certbot as an opt-in feature for hosts without a reverse proxy (e.g. Hostsharing); partially supersedes ADR 0004; updated plans, documentation, and migration guides

2026-07-07 14:40:11 +02:00
parent f6a876b29b
commit 142bc87604
8 changed files with 123 additions and 5 deletions
@@ -0,0 +1,67 @@
+# Optional Managed nginx/TLS Container
+
+**Status:**
+- proposed: 2026-07-07
+- accepted: 2026-07-07
+- rejected: -
+- superseded: -
+
+**Decision [accepted]:** GitTally 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
+
+GitTally must run on Hostsharing managed container environments.
+These hosts provide Docker but no root access and no host web server that GitTally could sit behind.
+Without the managed nginx container, GitTally 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 GitTally)
+
+### Host reverse proxy only
+
+#### Advantages
+
+- No container lifecycle or certificate code in GitTally.
+
+#### Disadvantages
+
+- Unusable on Hostsharing container hosts — the primary deployment target.
+
+### Opt-in managed nginx+certbot container
+
+GitTally 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 GitTally.
+
+### External compose stack
+
+#### Advantages
+
+- Keeps GitTally 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.