docs(tls): document ingress controller TLS termination #531

Merged

fuzzy merged 1 commit from docs/tls into main

2026-08-04 20:34:40 +00:00

automation commented

2026-08-04 20:28:25 +00:00

Owner

What

Document TLS termination for thwap-pagesd. TLS is terminated by the ingress controller, not the daemon, which listens on plain HTTP (:8080) inside the cluster.

Root README — a new "TLS termination" section covering:
- Daemon API/webhook: enable ingress.enabled in the Helm chart with ingress.tls + a cert-manager cluster-issuer annotation, and set webhook.public_url to the https:// URL.
- Served sites: site/preview Ingresses rely on the shared controller for TLS — a wildcard *.{base_domain} certificate or cert-manager dns01 covers default hosts; custom domains need their own certs.
- Adds an ingress controller prerequisite.
Chart README — a "TLS termination" subsection with a concrete ingress.tls + cert-manager annotation example.

Why

Phase 9 task #121 — the task explicitly permits documenting the ingress-controller dependency instead of terminating TLS in the daemon, which matches the in-cluster architecture.

Testing

helm lint deploy/charts/thwap-pagesd — 0 failures
helm template renders the documented ingress.tls + cert-manager annotation example correctly
go build ./..., go test -race -count=1 ./... — full suite passes (no Go changes)
pre-commit hooks all pass

Breaking Changes

None (documentation only).

Notes

Issue #121 closed via the Forgejo API as part of this task per the workflow.

Closes #121

## What Document TLS termination for thwap-pagesd. TLS is terminated by the ingress controller, not the daemon, which listens on plain HTTP (`:8080`) inside the cluster. - **Root README** — a new "TLS termination" section covering: - **Daemon API/webhook**: enable `ingress.enabled` in the Helm chart with `ingress.tls` + a cert-manager `cluster-issuer` annotation, and set `webhook.public_url` to the `https://` URL. - **Served sites**: site/preview Ingresses rely on the shared controller for TLS — a wildcard `*.{base_domain}` certificate or cert-manager `dns01` covers default hosts; custom domains need their own certs. - Adds an ingress controller prerequisite. - **Chart README** — a "TLS termination" subsection with a concrete `ingress.tls` + cert-manager annotation example. ## Why Phase 9 task #121 — the task explicitly permits documenting the ingress-controller dependency instead of terminating TLS in the daemon, which matches the in-cluster architecture. ## Testing - [x] `helm lint deploy/charts/thwap-pagesd` — 0 failures - [x] `helm template` renders the documented `ingress.tls` + cert-manager annotation example correctly - [x] `go build ./...`, `go test -race -count=1 ./...` — full suite passes (no Go changes) - [x] pre-commit hooks all pass ## Breaking Changes None (documentation only). ## Notes - Issue #121 closed via the Forgejo API as part of this task per the workflow. Closes #121

automation added 1 commit

2026-08-04 20:28:25 +00:00

docs(tls): document ingress controller TLS termination

Test and Release / lint (pull_request) Successful in 24s

Details

Test and Release / test (pull_request) Successful in 24s

Details

13a8bda833

TLS is terminated by the ingress controller, not the daemon, which
listens on plain HTTP (:8080) inside the cluster. Document the two TLS
surfaces:

- Daemon API/webhook: enable ingress.enabled in the Helm chart with
  ingress.tls and a cert-manager cluster-issuer annotation, and set
  webhook.public_url to the https:// URL
- Served sites: site and preview Ingresses rely on the shared controller
  for TLS, with a wildcard *.base_domain certificate or cert-manager
  dns01 covering default hosts and per-host certs for custom domains

Add an ingress controller prerequisite and a TLS example to both the
root README and the chart README. Mark task done in ROADMAP.md.

closes #121

automation added the

Kind/Documentation

label

2026-08-04 20:28:29 +00:00

fuzzy scheduled this pull request to auto merge when all checks succeed

2026-08-04 20:29:27 +00:00

the.auditor approved these changes

2026-08-04 20:34:38 +00:00

the.auditor left a comment

Review

Documentation-only PR; no blocking issues. All claims verified against the code and chart:

Daemon listens on plain HTTP :8080 (chart service.yaml port 8080 / deployment containerPort: 8080, config default listener.address: ":8080"); there is no TLS listener. Accurate.
Site and preview Ingresses (internal/kubernetes/templates.go:260, :291) carry no tls spec — they rely on the shared ingress controller, exactly as documented. Hosts are {name}.{base_domain} or the custom domain, and previews live at /preview/{branch}.
PreviewURL hardcodes the https:// scheme (kubernetes.go:275), so the guidance to set webhook.public_url to an https:// URL is consistent with how the daemon generates preview/webhook URLs.
The chart example (ingress.enabled/ingress.annotations/ingress.tls, config.webhook.public_url, config.kubernetes.base_domain) matches keys present in values.yaml and the ingress.yaml template.
The ingress-controller prerequisite was already implicit (site ingresses reference ingress_class); adding it to the prerequisites list is a genuine gap-fill, and the ROADMAP checkbox for #121 is properly flipped.

No non-blocking issues worth filing.

Approving.

## Review Documentation-only PR; no blocking issues. All claims verified against the code and chart: - Daemon listens on plain HTTP `:8080` (chart `service.yaml` port 8080 / deployment `containerPort: 8080`, config default `listener.address: ":8080"`); there is no TLS listener. Accurate. - Site and preview Ingresses (`internal/kubernetes/templates.go:260`, `:291`) carry no `tls` spec — they rely on the shared ingress controller, exactly as documented. Hosts are `{name}.{base_domain}` or the custom domain, and previews live at `/preview/{branch}`. - `PreviewURL` hardcodes the `https://` scheme (`kubernetes.go:275`), so the guidance to set `webhook.public_url` to an `https://` URL is consistent with how the daemon generates preview/webhook URLs. - The chart example (`ingress.enabled`/`ingress.annotations`/`ingress.tls`, `config.webhook.public_url`, `config.kubernetes.base_domain`) matches keys present in `values.yaml` and the `ingress.yaml` template. - The ingress-controller prerequisite was already implicit (site ingresses reference `ingress_class`); adding it to the prerequisites list is a genuine gap-fill, and the ROADMAP checkbox for #121 is properly flipped. No non-blocking issues worth filing. Approving.

fuzzy merged commit 13a8bda833 into main

2026-08-04 20:34:40 +00:00

fuzzy deleted branch docs/tls

2026-08-04 20:34:40 +00:00