# Почта техподдержки

Для `support@moon-well.online` используется отдельный контейнер
[Stalwart Mail Server](https://stalw.art/). Он предоставляет SMTP, IMAP,
антиспам, DKIM и административный интерфейс. Данные и конфигурация хранятся
в именованных Docker volumes и переживают пересоздание контейнера.

## Что требуется от сервера

- постоянный публичный IPv4-адрес;
- возможность принимать TCP-соединения на порты `25`, `465`, `587`, `993`;
- разрешённый исходящий TCP-порт `25`;
- PTR/rDNS для IP со значением `mail.moon-well.online`;
- доступ к управлению DNS-зоной `moon-well.online`.

Без корректного PTR исходящие сообщения часто попадают в спам. Некоторые
хостинги блокируют исходящий порт 25 — это нужно проверить до настройки.

## Первый запуск

```bash
./scripts/mail-server.sh init
```

Проверь значения в `.env.mail`. Затем создай DNS-запись:

```text
mail.moon-well.online.  A  <публичный IPv4 сервера>
```

Запусти сервер:

```bash
./scripts/mail-server.sh up
./scripts/mail-server.sh credentials
```

Административный HTTP-порт намеренно доступен только на loopback-интерфейсе.
Открой туннель со своего компьютера:

```bash
ssh -L 8081:127.0.0.1:8081 <пользователь>@<сервер>
```

После этого открой `http://127.0.0.1:8081/admin` и войди с временными
реквизитами из команды `credentials`.

## Мастер Stalwart

Используй следующие значения:

- Server hostname: `mail.moon-well.online`
- Default email domain: `moon-well.online`
- Automatically obtain TLS certificate: включено
- Generate email signing keys: включено
- Storage: локальный RocksDB
- Directory: Internal Directory
- Logging: Console

Если DNS размещён у поддерживаемого Stalwart провайдера, подключи его в
последнем шаге. Тогда сертификат выпускается через DNS-01 без занятия
публичного порта 443. Иначе понадобится отдельно передать серверу TLS-сертификат
или временно предоставить ему порт 443 для ACME-проверки.

Сохрани постоянные реквизиты администратора, показанные мастером, и
перезапусти контейнер:

```bash
./scripts/mail-server.sh restart
```

Создай обычный пользовательский аккаунт `support@moon-well.online`.
Административный аккаунт нельзя использовать в почтовом клиенте.

## DNS после мастера

В панели Stalwart открой:

`Management → Domains → Domains → moon-well.online → View DNS Zone file`

Перенеси предложенные записи в DNS-панель. В обязательный минимум входят:

- MX;
- SPF;
- DKIM;
- DMARC;
- записи автоконфигурации, которые предложит Stalwart.

Значение DKIM нужно брать только из созданной установки: ключ генерируется
индивидуально. Не копируй DKIM из примеров.

## Настройка почтового клиента

```text
Адрес:               support@moon-well.online
IMAP-сервер:         mail.moon-well.online
IMAP-порт:           993
Шифрование IMAP:     SSL/TLS
SMTP-сервер:         mail.moon-well.online
SMTP-порт:           465
Шифрование SMTP:     SSL/TLS
SMTP-аутентификация: включена
Логин:               support@moon-well.online
```

## Подключение Laravel

После создания ящика укажи в production `.env`:

```dotenv
MAIL_MAILER=smtp
MAIL_SCHEME=smtps
MAIL_HOST=mail.moon-well.online
MAIL_PORT=465
MAIL_USERNAME=support@moon-well.online
MAIL_PASSWORD=<пароль ящика>
MAIL_FROM_ADDRESS=support@moon-well.online
MAIL_FROM_NAME="${APP_NAME}"
```

Затем сбрось и пересобери кэш конфигурации:

```bash
docker compose exec -T laravel.test php artisan optimize:clear
docker compose exec -T laravel.test php artisan config:cache
```

## Резервное копирование

В бэкап должны попадать оба именованных volume:

- `stalwart-config`;
- `stalwart-data`.

Перед восстановлением используй ту же minor-версию образа Stalwart, что указана
в `compose.mail.yaml`.

## TLS на production-сервере

На production сертификат выпускает системный Certbot через Nginx. Контейнер
получает read-only каталог `MAIL_TLS_DIR` и использует:

```text
/run/stalwart-tls/fullchain.pem
/run/stalwart-tls/privkey.pem
```

Deploy-hook Certbot копирует обновлённые файлы в этот каталог и перезапускает
только контейнер Stalwart, чтобы он перечитал сертификат.

Hook устанавливается из `scripts/deploy-mail-certificate.sh`.

Внешний HTTPS-доступ к панели и JMAP проксируется через Nginx. Готовая
конфигурация находится в `ops/nginx-mail.conf`; внутренний HTTP-порт Stalwart
остаётся доступен только на `127.0.0.1`.

После установки сертификата его нужно добавить в Stalwart и выбрать как
сертификат по умолчанию. Для HTTP-настроек за Nginx также включается
`useXForwarded`, чтобы автоматические блокировки применялись к реальному
адресу клиента, а не к Docker gateway.