app-catalog-felhom.eu/REPORT.md

REPORT — App-email smtp_mapping for Vaultwarden + Mealie

Date: 2026-06-29 Task: SMTP app-relay (catalog leg). Add smtp_mapping to the two spike-proven apps so deployed apps can send outbound email via the managed path (app → in-controller shim → hub → Resend). Implements felhom.eu/documentation/audits/SPIKE-smtp-app-relay-2026-06-28.md §7.

Files modified

• templates/vaultwarden/.felhom.yml — added smtp_mapping (STARTTLS; SMTP_SECURITY=starttls, SMTP_FROM=vaultwarden@felhom.eu, SMTP_FROM_NAME, + SMTP_ACCEPT_INVALID_CERTS/HOSTNAMES). SMTP_USERNAME/ SMTP_PASSWORD intentionally unset.
• templates/vaultwarden/docker-compose.yml — reference the injected ${SMTP_*} keys (harmless defaults).
• templates/mealie/.felhom.yml — added smtp_mapping (plaintext; SMTP_AUTH_STRATEGY=NONE on :2525, SMTP_FROM_EMAIL=mealie@felhom.eu, SMTP_FROM_NAME).
• templates/mealie/docker-compose.yml — reference the injected ${SMTP_*} keys (harmless defaults).
• README.md — documented the smtp_mapping pattern (field table + STARTTLS-vs-plaintext guidance) so further apps are easy adds.
• CHANGELOG.md — entry.

How it works

When app-email is on (global toggle + per-app toggle), the controller injects at deploy/redeploy: SMTP_HOST = the on-box shim, SMTP_PORT = 2525, From = <app>@felhom.eu, the app's security value, plus the mapping's fixed extra vars. The values are derived from settings each compose — never persisted to app.yaml. An empty SMTP_HOST (toggle off) leaves the app's mail disabled.

Validation

• Both .felhom.yml and both docker-compose.yml YAML-validated OK.
• Field names match the controller's stacks.SMTPMapping struct tags exactly (covered by the controller's TestMetadata_SMTPMappingParse and the Vaultwarden/Mealie env-injection tests).
• Git sync picks up the change within ~15 min (or via "Sablonok frissítése").
• The end-to-end relay path these mappings feed (app → on-box shim → hub → Resend) was live-validated on guest 9201 / hub v0.18.0 on 2026-06-29 with a Vaultwarden-shaped message (From vaultwarden@felhom.eu, inline CID image) → Resend 250 queued; see felhom-controller/REPORT.md. Deploying the Vaultwarden app and using its admin "send test email" is the recommended final smoke for the app's own SMTP client (spike-proven).

Notes / deviation

• Mealie uses plaintext (NONE), not STARTTLS. Mealie has no accept-invalid-cert option, so STARTTLS to the self-signed shim would fail cert verification; the spike validated Mealie via plaintext on :2525 (the shim is Docker-network-only, never published). This is the spike-faithful choice (spike §7 mealie table = NONE), deviating from the prompt's Part-4 "TLS for mealie" wording.
• Scope = these two proven apps only. Further apps (immich, nextcloud, …) are a follow-on: each just needs its own smtp_mapping block + the matching compose ${VAR} lines.