08-email.md (6013B)
1 # Email (saída) 2 3 [← Índice](README.md) 4 5 ## Arquitectura actual 6 7 - **Predefinição:** envio via **Mailgun HTTP API** (`email/configure_mailgun.py`). 8 - **Estado:** `/etc/runv-email.json` 9 - **Segredos:** `/etc/runv-email.secrets.json` (permissões restritas; não versionar). 10 11 ## Modo legado 12 13 - SMTP via `msmtp` / `sendmail`: flags `--legacy-smtp` ou `configure_msmtp_legacy.py` (detalhes nas docstrings e `--help` dos scripts em `email/`). 14 15 ## Biblioteca 16 17 - `email/lib/mailer.py` — envio reutilizável; templates em `email/templates/`. 18 - Variável `RUNV_EMAIL_ROOT` ou `email_package_root` no JSON para o fluxo `entre` localizar templates. 19 20 ## Integração com `entre` 21 22 - Notificações ao admin usam `admin_email` no `config.toml` do terminal **ou** fallback em `/etc/runv-email.json` (comportamento verificado no código de `terminal/` + `email/lib`). 23 24 ## O que o repo não é 25 26 - **Não** substitui a instalação Postfix/Dovecot/Roundcube no servidor (isso é operação de sistema). 27 - **Não** usa Mailgun para correio de membros. 28 29 ## Dois canais de email (não misturar) 30 31 | Canal | Função | Config no servidor | 32 |-------|--------|-------------------| 33 | **Mailgun** | Transacional / admin (`entre`, boas-vindas, avisos) | `/etc/runv-email.json` | 34 | **MTA local** | Correio `@runv.club` para membros (caixa, webmail, encaminhamento) | Postfix + Dovecot + Roundcube (fora deste repo) | 35 36 O Mailgun **não** deve receber pedidos de alias `username@runv.club → Gmail`. Isso é papel do **Postfix** (ou mapa virtual equivalente) já instalado na VPS. 37 38 ## Aliases de email para membros 39 40 O fluxo runv regista pedidos e aprovações em JSON. O encaminhamento real pode ser aplicado no Postfix com `runv-admin-email-alias sync` quando `/etc/runv-member-mail.json` estiver activo (ver abaixo). 41 42 Um membro pode pedir um alias fixo: 43 44 `username@runv.club` → email externo de destino 45 46 Por omissão o membro pede no terminal, o admin aprova, e o registo fica em JSON. Com sync Postfix configurado, o encaminhamento no MTA local pode ser automático após `approve` ou via `sync`. 47 48 ### Membro 49 50 **Sem `sudo` e sem root.** O membro corre os comandos na própria sessão SSH (conta Unix da comunidade, ex. `pmurad`). O sistema usa o username dessa sessão; contas de operador/admin (ex. `pmurad-admin`) **não** estão em `runv-members` e não podem pedir alias por design. 51 52 ```bash 53 runv-email-alias request usuario@example.org 54 runv-email-alias status 55 runv-email-alias cancel 56 ``` 57 58 - `status` lê `/var/lib/runv/email-aliases.json` (modo `640`, grupo `runv-members`). 59 - `request` / `cancel` escrevem só na fila `email-alias-queue/` (modo `2770`, mesmo grupo). 60 - Aprovação e alteração do JSON activo são sempre **admin** (`runv-admin-email-alias` como root). 61 62 O alias é sempre `username@runv.club` (username Unix do utilizador que corre o comando). Não é possível escolher outro nome de alias. 63 64 ### Admin 65 66 ```bash 67 sudo runv-admin-email-alias pending 68 sudo runv-admin-email-alias list 69 sudo runv-admin-email-alias approve pablo 70 sudo runv-admin-email-alias approve pablo --sync-mail 71 sudo runv-admin-email-alias sync 72 sudo runv-admin-email-alias reject pablo --reason "email destino inválido" 73 ``` 74 75 ### Inventário e sync Postfix (MTA local) 76 77 Na VPS, antes de activar sync: 78 79 ```bash 80 sudo python3 scripts/admin/discover_mail_stack.py 81 ``` 82 83 Copiar e editar o exemplo: 84 85 ```bash 86 sudo cp email/config/runv-member-mail.example.json /etc/runv-member-mail.json 87 # enabled: true após validar postconf virtual_alias_maps 88 sudo python3 scripts/admin/sync_member_email_aliases.py --dry-run 89 sudo runv-admin-email-alias sync 90 ``` 91 92 Na vossa VPS o Postfix usa **`mysql:/etc/postfix/mysql-virtual-alias-maps.cf`** — use backend `postfix-mysql` (não adicione mapa hash paralelo). 93 94 ```bash 95 sudo python3 scripts/admin/inspect_postfix_mysql_aliases.py 96 sudo cp email/config/runv-member-mail.example.json /etc/runv-member-mail.json 97 # editar enabled + colunas/tabela se o inspect sugerir 98 sudo runv-admin-email-alias sync 99 ``` 100 101 O sync faz UPSERT na tabela de aliases e `reload postfix`. **Não** altera Mailgun. 102 103 ### Setup inicial no servidor 104 105 ```bash 106 sudo python3 scripts/admin/setup_email_aliases.py 107 sudo python3 scripts/admin/setup_email_aliases.py --add-existing-users 108 ``` 109 110 Depois instalar os comandos com `sudo python3 tools/tools.py` (ver [05-tools-and-system-experience.md](05-tools-and-system-experience.md)). 111 112 ### Ficheiros e permissões 113 114 | Caminho | Função | 115 |---------|--------| 116 | `/var/lib/runv/email-aliases.json` | Aliases aprovados (activos) | 117 | `/var/lib/runv/email-aliases.lock` | Lock para escrita segura | 118 | `/var/lib/runv/email-alias-queue/` | Pedidos pendentes | 119 | `.../approved/`, `.../rejected/`, `.../cancelled/` | Histórico de pedidos | 120 121 Permissões sugeridas após o setup: 122 123 | Caminho | Modo | Dono:grupo | 124 |---------|------|------------| 125 | `/var/lib/runv/email-aliases.json` | 640 | root:runv-members | 126 | `/var/lib/runv/email-aliases.lock` | 660 | root:runv-members | 127 | `/var/lib/runv/email-alias-queue/` | 2770 | root:runv-members | 128 129 Variáveis de ambiente para testes locais: `RUNV_EMAIL_ALIASES_PATH`, `RUNV_EMAIL_ALIASES_LOCK_PATH`, `RUNV_EMAIL_ALIAS_QUEUE_DIR`, `RUNV_EMAIL_ALIAS_DOMAIN`. 130 131 Mais detalhe dos comandos: [17-community-commands.md](17-community-commands.md). 132 133 ### O que isto não faz 134 135 - Não cria mailbox. 136 - Não recebe email. 137 - Não envia email (além do stack transacional já existente). 138 - Não configura DNS. 139 - Não configura SPF/DKIM/DMARC. 140 - Não configura Postfix/Dovecot. 141 - Não configura Mailgun para aliases de membros. 142 - Não configura Roundcube/Dovecot directamente (só mapa virtual Postfix quando sync activo). 143 144 ### Próximo passo futuro 145 146 Suporte a backends além de `postfix-hash` (ex. SQL já usado pelo servidor) após mapear o que `discover_mail_stack.py` reportar. 147 148 ## Testes 149 150 - Existem testes em `email/tests/` (ex.: `test_mailgun_client.py`). Ver [14-smoke-tests-and-validation.md](14-smoke-tests-and-validation.md). 151 152 Próximo: [09-terminal-entre.md](09-terminal-entre.md).