mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 10:59:59 +00:00
87 lines
4.1 KiB
Markdown
87 lines
4.1 KiB
Markdown
# sys-svc-mail
|
||
|
||
## Description
|
||
|
||
The `sys-svc-mail` role acts as the **central mail orchestration layer** in the Infinito.Nexus stack.
|
||
It wires together:
|
||
|
||
- [Stalwart](https://stalw.art/) as a full-featured mail server (when available),
|
||
- [msmtp](https://marlam.de/msmtp/) as a lightweight sendmail-compatible SMTP client, and
|
||
- an optional local SMTP relay (Postfix) for hosts **without** Stalwart.
|
||
|
||
For more background on the underlying protocol, see [Simple Mail Transfer Protocol (SMTP) on Wikipedia](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol).
|
||
|
||
## Overview
|
||
|
||
This role provides a **unified mail setup** for your hosts:
|
||
|
||
- If the host is part of the active mail provider's group (`MAIL_PROVIDER`), it:
|
||
- asserts the provider endpoint was preloaded (submission token present),
|
||
- and prepares the system to send emails through the provider using the `sys-svc-mail-msmtp` role.
|
||
|
||
- If the host is **not** running Stalwart, 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 Stalwart or a local relay.
|
||
|
||
## Cosmos
|
||
|
||
The diagram places sys-svc-mail in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph role [sys-svc-mail 💻]
|
||
svc_svc_mail["svc-mail"]
|
||
end
|
||
```
|
||
|
||
Solid `1:1` edges are fixed relationships; dashed `0..1` edges are conditional (enabled only in matching deployments); red `0..0` edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in `meta/main.yml`.
|
||
|
||
## 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:
|
||
- **Stalwart-backed delivery** (with authentication tokens), or
|
||
- a **local SMTP relay on localhost**,
|
||
depending on the presence of `web-app-stalwart` 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
|
||
|
||
- 🔄 **Mail-provider integration (when available)**
|
||
- Asserts the active provider's submission token was provisioned before configuring external mail.
|
||
- Routes outbound mail through the provider via `sys-svc-mail-msmtp`.
|
||
|
||
- 💡 **Smart Fallback to Localhost**
|
||
- If no `web-app-stalwart` 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 Stalwart 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:
|
||
- Stalwart: <https://stalw.art/>
|
||
- 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>
|
||
|
||
## Credits
|
||
|
||
Implemented by **[Kevin Veen-Birkenbach](https://www.veen.world)**.
|
||
Part of the [Infinito.Nexus Project](https://s.infinito.nexus/code) and maintained by [Kevin Veen-Birkenbach](https://www.veen.world).
|
||
Licensed under the [Infinito.Nexus Community License (Non-Commercial)](https://s.infinito.nexus/license).
|