computer-playbook/docs/administration/configuration/email.md

Email Configuration 📬

This page documents the administrator-facing surface of outgoing email configuration. For the plugin contract and extension rules, see email.md.

Infinito.Nexus exposes outgoing email settings through the email lookup plugin. All role templates and tasks read email settings via lookup('email') (global) or lookup('email', '<application_id>') (per-app). No global SYSTEM_EMAIL_* variable file ships with the project. Resolution defaults derive from project-wide inputs: DOMAIN_PRIMARY, TLS_ENABLED, DOCKER_IN_CONTAINER, the web-app-mailu group membership, and the no-reply user.

Resolved Keys 🔑

Every call returns a flat dict with the following keys. Each key MAY be overridden from inventory by setting the matching SYSTEM_EMAIL_<KEY> variable (uppercase, with the SYSTEM_EMAIL_ prefix).

Key	Override Variable	Default	Meaning
enabled	SYSTEM_EMAIL_ENABLED	true	Whether outgoing mail is enabled.
timeout	SYSTEM_EMAIL_TIMEOUT	"30"	SMTP/client timeout in seconds.
external	SYSTEM_EMAIL_EXTERNAL	true if the host is in the web-app-mailu group, else false	True when a web-app-mailu host is reachable (otherwise local delivery).
environment	SYSTEM_EMAIL_ENVIRONMENT	external if external or TLS_ENABLED, else localhost, plus _container suffix if DOCKER_IN_CONTAINER and TLS_ENABLED is false	One of external, external_container, localhost, localhost_container.
domain	SYSTEM_EMAIL_DOMAIN	DOMAIN_PRIMARY	Primary mail domain.
tls	SYSTEM_EMAIL_TLS	false if not external, else TLS_ENABLED	True when SMTPS SHOULD be used.
port	SYSTEM_EMAIL_PORT	465 when external and tls, else 25	SMTP port.
host	SYSTEM_EMAIL_HOST	localhost for external_container, localhost, localhost_container, else the web-app-mailu domain	SMTP host.
auth	SYSTEM_EMAIL_AUTH	false for external_container and localhost, else equal to tls	Whether SMTP auth is required.
start_tls	SYSTEM_EMAIL_START_TLS	false	Whether STARTTLS is used.
smtp	SYSTEM_EMAIL_SMTP	true	Whether SMTP delivery is enabled.
from	SYSTEM_EMAIL_FROM	email of the no-reply user when external, else root@<inventory_hostname>.localdomain	Envelope/from address.
username	SYSTEM_EMAIL_USERNAME	equal to from	SMTP username.
password	SYSTEM_EMAIL_PASSWORD	no-reply user's web-app-mailu token, else empty string	SMTP password.

Per-Application Overrides 🧩

Applications MAY override any subset of these keys under compose.services.email in their role or inventory.

Role defaults:

# roles/<application_id>/config/main.yml
compose:
  services:
    email:
      host: smtp.app.example.org
      port: 587
      tls: true

Inventory overrides:

# group_vars/<group>.yml or host_vars/<host>.yml
applications:
  web-app-nextcloud:
    compose:
      services:
        email:
          username: nextcloud@example.org

Overrides are merged on top of the resolved defaults. Keys MUST use the short, lowercased names listed above.

Precedence 📊

For each key, the first defined source wins:

1. applications['<application_id>'].compose.services.email.<key>, applied only when an application_id is passed.
2. A SYSTEM_EMAIL_<KEY> variable defined in inventory, group vars, or host vars. No such file ships with the project. This form is an escape hatch for site-specific overrides.
3. The plugin's built-in fallback computed from DOMAIN_PRIMARY, the web-app-mailu group, the no-reply user, and related inputs.

See Also 🔗

• email.md for the plugin contract and extension rules.