# smtp-relay

Postfix SMTP relay with Cyrus SASL authentication and TLS.

Used by Mailu (personal + Solidaria NGO) on valhalla to route outbound mail through
hermes, which has a trusted residential IP accepted by Gmail and Hotmail.

Image: `harbor.manabo.org/library/smtp-relay`  
Deployed on: hermes (`clusters/hermes/smtp-relay/` in asgard)

---

## Build

Con **mcp-build** (2026-07-29). Antes había un `scripts/build.sh` con Kaniko y un
`.gitea/workflows/build.yml`: **los dos se han borrado**. Kaniko y Gitea Actions se están
retirando, y este workflow además llevaba roto desde mayo — era el único del árbol que usaba
`actions/checkout@v4`, que necesita `node`, y el runner `:host` no lo tiene
(`Cannot find: node in PATH`). Fallaba en 70 s en cada push y **nadie se enteraba**: la imagen que
sostuvo el correo durante 70 días era del 20 de mayo.

```
trigger_build(repo_url="https://git.manabo.org/xavor/smtp-relay.git",
              ref="main", image_tag="dev", image_name="library/smtp-relay")
```

⚠️ `image_name` va **sin el host**. Con `harbor.manabo.org/library/smtp-relay` el destino sale
duplicado (`harbor.manabo.org/harbor.manabo.org/...`) y el push muere con `401`.

El despliegue se pinea a mano en `asgard/clusters/hermes/smtp-relay/kustomization.yaml`.

---

## Configuration

### Required Vault secrets (`app/smtp-relay/smtp-relay-sasl`)

| Key | Description |
|-----|-------------|
| `relay_user` | SASL username (e.g. `relayuser`) |
| `relay_pass` | SASL password (plaintext — stored in Vault) |
| `relay_domain` | SASL domain (e.g. `manabo.org`) |

### TLS (`certs/smtp-relay-tls`)

Wildcard cert for `relay.manabo.org` — pushed to Vault via PushSecret on valhalla.

### Env vars (from ExternalSecret)

| Var | Source |
|-----|--------|
| `RELAY_AUTH_USER` | `relay_user` |
| `RELAY_AUTH_PASS` | `relay_pass` |
| `RELAY_AUTH_DOMAIN` | `relay_domain` |

---

## How it works

- Listens on ports **25** (SMTP, TLS optional) and **587** (submission, TLS required)
- Uses `hostNetwork: true` — ports exposed directly on the hermes host IP
- Entrypoint creates a `sasldb2` user from the env vars on every start
- Only clients authenticated via SASL can relay mail
- TLS cert mounted from Vault ExternalSecret

---

## Gotchas

- **sasldb2 recreated on every restart**: credentials are read from env vars and
  `saslpasswd2` re-creates the sasldb. This is intentional (stateless SASL).
- **No DKIM**: DKIM signing is not implemented in this image. Relay delivers mail
  as-is; DKIM signatures must be added by the sending MTA (Mailu).

### Por qué la config es como es (incidente del 2026-07-29)

El correo saliente de `manabo.org` estuvo **semanas sin salir** por cinco fallos encadenados, cada
uno tapando al siguiente. Cuatro de los arreglos vivieron 70 días aplicados a mano sobre el
contenedor vivo, fuera de git. Están en la imagen desde el 2026-07-29. Relato completo en
`asgard/clusters/hermes/smtp-relay/README.md`. **Lo que no se puede tocar sin reabrirlo:**

- **`tlsmgr` en `master.cf`.** Sin ese daemon, `smtpd` **anuncia** `STARTTLS` en el `EHLO` y luego
  no puede hacerlo: `454 4.7.0 TLS not available due to local problem`. La capacidad anunciada no
  prueba la capacidad.
- **`postfix` en el grupo `sasl`** (`usermod -aG sasl postfix` en el Dockerfile). `/etc/sasldb2` es
  `root:sasl 0640`; sin el grupo, `smtpd` no puede abrirlo → `454 Temporary authentication failure`.
- **`smtpd_sasl_local_domain` sale del `entrypoint`, no de `main.cf`.** Tiene que ser el mismo
  `RELAY_AUTH_DOMAIN` con el que `saslpasswd2` crea la entrada del sasldb. Estaba declarado aparte
  como `$myhostname`, así que el realm era `relayuser@relay.manabo.org` y la entrada real
  `relayuser@manabo.org`. **No lo devuelvas a `main.cf`**: separados, vuelven a poder divergir.
- **`chroot = n` en todos los servicios de `master.cf`.** Con chroot, Postfix necesita
  `/var/spool/postfix/etc/resolv.conf` poblado en el build; sin él **no resuelve MX** y el correo se
  queda en cola con `Name service error`, aunque `getent hosts` dentro del contenedor sí resuelva
  (la herramienta de diagnóstico no ve lo mismo que el consumidor). En un contenedor el chroot no
  aporta nada: el contenedor **es** el jail.
- **`postlogd` + `maillog_file`.** Postfix escribe a syslog y aquí no corre ninguno ⇒ `kubectl logs`
  sale **vacío**. Sin esto, el incidente se diagnostica a ciegas — y es lo que permite ver si un
  despliegue futuro sale mal.

**Cómo se prueba un cambio de esta imagen antes de desplegarlo** (obligatorio: desplegar aquí es
reiniciar el único pod que sostiene el correo, y si falla **no hay alerta que lo diga, porque la
alerta es el correo**): arranca la imagen candidata aparte con el entrypoint real y las env de
producción, y exige `diff` vacío de `postconf -n` y `postconf -M` contra el contenedor en marcha.
Un diff limpio no basta: ejercita también `STARTTLS` y `AUTH PLAIN` contra ella (`235
Authentication successful`), que es lo que un diff de configuración no caza.