mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2025-12-07 09:56:41 +00:00

Files

Kevin Veen-Birkenbach 8e4ee723d7 Make mail stack optional for Infinito.Nexus deployments without Mailu (e.g. Raspberry Pi / robots)

Refactored mail-related roles to support running Infinito.Nexus on nodes without a dedicated mail server:
- Introduced sys-svc-mail as central mail orchestration role.
- Split msmtp handling into sys-svc-mail-msmtp.
- Added sys-svc-mail-smtp to provide a localhost-only Postfix relay when Mailu is not present.
- Updated alert/health roles to use the new mail orchestration.
- Avoid installing postfix inside containers via IS_CONTAINER guard.
- Adjusted WordPress role to use the new msmtp template path.

This allows lightweight deployments (e.g. Raspberry Pi, robots, edge nodes) to send mail via localhost without requiring a full Mailu stack.

ChatGPT discussion: https://chatgpt.com/share/6931edf1-cb98-800f-9e3c-a62d69ccb223

2025-12-04 21:24:53 +01:00

README.md

sys-svc-mail 📧

Description

The sys-svc-mail role acts as the central mail orchestration layer in the Infinito.Nexus stack.
It wires together:

Mailu as a full-featured mail server (when available),
msmtp as a lightweight sendmail-compatible SMTP client, and
an optional local SMTP relay (Postfix) for hosts without Mailu.

For more background on the underlying protocol, see Simple Mail Transfer Protocol (SMTP) on Wikipedia.

Overview

This role provides a unified mail setup for your hosts:

If the host is part of the web-app-mailu group, it:
- checks the reachability of the Mailu endpoint,
- triggers Mailu startup via the Infinito.Nexus helper (utils/load_app.yml),
- and prepares the system to send emails through Mailu using the sys-svc-mail-msmtp role.
If the host is not running Mailu, it:
- optionally configures a local SMTP relay via sys-svc-mail-smtp (Postfix on localhost:25),
- and still configures msmtp as a sendmail-compatible client.

This makes sys-svc-mail the canonical entrypoint for “mail capabilities” on a node, abstracting away whether the actual delivery happens via Mailu or a local relay.

Purpose

The main purpose of this role is to:

Provide a consistent mail-sending interface for all hosts in the Infinito.Nexus ecosystem.
Automatically choose between:
- Mailu-backed delivery (with authentication tokens), or
- a local SMTP relay on localhost, depending on the presence of web-app-mailu in the host’s groups.
Ensure that system services and applications can always send notifications (e.g. health checks, alerts, job results) without each role having to care about the underlying mail plumbing.

Features

🔄 Mailu Integration (when available)
- Checks Mailu reachability using Ansible’s uri module.
- Triggers Mailu startup via utils/load_app.yml.
- Ensures handlers are flushed/reset via utils/load_handlers.yml.
💡 Smart Fallback to Localhost
- If no web-app-mailu is present, the role can configure a local Postfix-based SMTP relay via sys-svc-mail-smtp.
- Combined with sys-svc-mail-msmtp, this enables sending mail via localhost:25 without additional configuration in other roles.
📨 msmtp Client Configuration
- Delegates installation and configuration of msmtp to sys-svc-mail-msmtp.
- Supports both authenticated Mailu delivery and unauthenticated localhost-based delivery.
🧩 Composable Design
- Uses internal run_once_* flags to avoid repeated setup.
- Cleanly integrates with the Infinito.Nexus stack and shared utilities.

Further Resources

Mail server:
- Mailu: https://mailu.io/
- SMTP (protocol): https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
SMTP client:
- msmtp: https://marlam.de/msmtp/
- msmtp on Wikipedia: https://en.wikipedia.org/wiki/Msmtp
Infinito.Nexus:
- Main repository: https://s.infinito.nexus/code
- Documentation: https://docs.infinito.nexus

README.md Unescape Escape