mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 02:54:26 +00:00
kevinveenbirkenbachandClaude Opus 4.7
286408fa91
Move utils/roles/applications/files.py to utils/roles/mapping.py and add a data-driven role-type detector in utils/roles/type.py. Each entry in ROLE_FILES carries per-role-type allowed/mandatory flags plus marker entries that drive get_role_types(); a role MAY belong to several types (e.g. an application that also ships a system service). Add cli/meta/roles/mapping with files / types / markers subcommands so contributors can query the schema in text or JSON. Move cli/meta/applications/ to cli/meta/roles/applications/ and adjust PROJECT_ROOT parents indices accordingly. Move docs/contributing/design/services/ to docs/contributing/design/role/services/ and document the mapping in docs/contributing/design/role/mapping.md per documentation.md. Replace the narrow test_app_only_files with a generalist tests/integration/roles/meta/test_mapping.py that walks every role and every ROLE_FILES entry and reports forbidden files, missing mandatory files, forbidden entries, and missing mandatory entries in one structured fail report. meta/info.yml and meta/users.yml are now allowed across every role type. Create the seven mandatory files surfaced by the generalist test (README.md for desk-keepassxc, desk-obs, web-svc-cdn following readme_md.md, plus tasks/main.yml stubs for svc-db-memcached, svc-db-redis, sys-svc-proxy, web-app-socialhome). Audit and rewrite touched markdown for documentation.md compliance: replace em-dashes with fluent sentences, drop SPOT self-labels, fix all broken relative links introduced by the services/ move. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# Email Configuration 📬
|
|
|
|
This page documents the administrator-facing surface of outgoing email
|
|
configuration. For the plugin contract and extension rules, see
|
|
[email.md](../../contributing/design/role/services/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:
|
|
|
|
```yaml
|
|
# roles/<application_id>/config/main.yml
|
|
compose:
|
|
services:
|
|
email:
|
|
host: smtp.app.example.org
|
|
port: 587
|
|
tls: true
|
|
```
|
|
|
|
Inventory overrides:
|
|
|
|
```yaml
|
|
# 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](../../contributing/design/role/services/email.md) for the plugin contract and extension rules.
|