Справочник по установке, настройке и эксплуатации Mailcow

[Admin]

Справочник по установке, настройке и эксплуатации Mailcow (Пункты 1–100)

Установка и Docker

1. Команда sudo docker compose pull скачивает все необходимые Docker-образы, указанные в файле docker-compose.yml, без запуска контейнеров.
2. Команда sudo docker compose up -d скачивает образы (если их нет), создает и запускает все контейнеры Mailcow в фоновом режиме.
3. Команда sudo docker compose down останавливает и удаляет все контейнеры и сети Mailcow, но сохраняет тома с данными.
4. Команда sudo docker compose down -v полностью удаляет все контейнеры, сети и тома (включая все письма и базу данных).
5. sudo docker compose ps показывает статус всех контейнеров Mailcow (работает/остановлен).
6. sudo docker compose logs --tail=200 <имя_контейнера> показывает последние 200 строк логов указанного контейнера (например, nginx-mailcow, php-fpm-mailcow).
7. Конфликт портов — самая частая проблема при запуске Mailcow, когда порт уже занят другим сервисом (nginx, apache).
8. Ошибка address already in use означает, что порт, который пытается занять контейнер, уже используется другим процессом на хосте.
9. Для тестового запуска Mailcow можно временно остановить системный Nginx командой sudo systemctl stop nginx.
10. Чтобы Nginx не запускался автоматически, используется команда sudo systemctl disable nginx.
11. Статус контейнера Healthy означает, что он не просто запущен, но и успешно прошел внутренние проверки работоспособности.
12. Статус Started / Running означает, что процесс контейнера запущен, но его функциональность может быть еще не готова (например, база данных инициализируется).
13. Конфликт Docker-сетей возникает, когда подсеть, которую пытается создать Mailcow, уже используется другой сетью Docker.
14. Ошибка Pool overlaps with other one on this address space решается изменением подсети в переменной IPV4_NETWORK в файле .env.
15. Для смены подсети Mailcow нужно изменить третий октет в IPV4_NETWORK (например, с 172.22.1 на 172.22.2).
16. В качестве гарантированно свободной подсети можно использовать диапазон 10.0.0.0/24 (установив IPV4_NETWORK=10.0.0).
17. Файл .env в директории /opt/mailcow-dockerized является основным конфигурационным файлом Mailcow.
18. MAILCOW_HOSTNAME в файле .env — это полное доменное имя (FQDN) вашего почтового сервера (например, mail.domain.tld).
19. Переменная HTTP_PORT в .env задает порт на хосте, который будет слушать веб-интерфейс Mailcow по HTTP.
20. Переменная HTTPS_PORT в .env задает порт на хосте для HTTPS-интерфейса Mailcow.
21. Если HTTPS_PORT закомментирован, Mailcow использует стандартный порт 443.
22. SKIP_LETS_ENCRYPT=y в .env отключает встроенный ACME-клиент Mailcow, что необходимо при использовании внешнего прокси и Certbot.
23. HTTP_REDIRECT=y заставляет Mailcow принудительно перенаправлять все HTTP-запросы на HTTPS.
24. Переменная ADDITIONAL_SERVER_NAMES указывает дополнительные доменные имена, на которые должен отвечать веб-интерфейс Mailcow.
25. TZ=Europe/Moscow задает часовой пояс для контейнеров Mailcow.
26. DBPASS и DBROOT — автоматически сгенерированные пароли к базе данных MySQL/MariaDB.
27. При изменении файла .env необходимо перезапустить Mailcow: sudo docker compose down && sudo docker compose up -d.

Обратный прокси (Reverse Proxy)

28. При использовании внешнего обратного прокси (например, Nginx) Mailcow должен слушать на нестандартных портах (например, 8080 и 8443).
29. Внешний Nginx принимает трафик на стандартных портах 80 и 443 и перенаправляет его на внутренние порты Mailcow.
30. Ключевой заголовок для Mailcow при работе за прокси: proxy_set_header X-Forwarded-Proto https;.
31. Он сообщает Mailcow, что исходный запрос был по HTTPS, даже если внутри он идет по HTTP.
32. Для работы с Certbot в конфиге Nginx обязательно должен быть блок server для порта 80.
33. Certbot для проверки домена использует временную директорию location /.well-known/acme-challenge/.
34. После успешного получения сертификата Certbot автоматически модифицирует конфиг Nginx, добавляя настройки SSL.
35. Ошибка "if directive is not allowed here" возникает, когда Certbot добавляет неправильный редирект в конфиг Nginx.
36. Правильный редирект HTTP -> HTTPS в Nginx выглядит так: return 301 https://$host$request_uri;.
37. Для проксирования HTTPS-трафика внешний Nginx должен иметь свой собственный валидный SSL-сертификат (от Certbot).
38. Конфиг внешнего Nginx должен быть разделен на два блока server: для порта 80 (редирект) и для порта 443 (прокси).
39. В блоке для порта 443 обязательно должна быть директива proxy_pass http://127.0.0.1:8087; (или ваш внутренний порт).
40. При использовании внешнего прокси встроенный HTTPS-порт Mailcow (например, 8443) остается неиспользуемым для внешнего трафика.

Решение проблем с запуском и подключением

41. Ошибка "Waiting for SQL..." в логах php-fpm-mailcow означает, что контейнер ждет готовности базы данных MySQL.
42. Это нормально для первого запуска и может длиться несколько минут, пока MySQL инициализируется.
43. Логи mysql-mailcow показывают прогресс инициализации базы данных и момент, когда она готова к подключениям (ready for connections).
44. Ошибка HTTP 502 Bad Gateway от Nginx означает, что Nginx не может связаться с бэкендом (PHP-FPM).
45. Самоподписанный сертификат вызывает предупреждение браузера "Недействительный сертификат" или "Ваше соединение не защищено".
46. Ошибка "Циклическое перенаправление" в Firefox при доступе по HTTP возникает из-за принудительного редиректа Mailcow на HTTPS.
47. Ошибка в Chrome "Этот сайт не может обеспечить безопасное подключение" возникает из-за проблем с SSL/TLS рукопожатием.
48. Команда sudo nginx -t проверяет синтаксис конфигурационных файлов Nginx и указывает на ошибки.
49. Ошибка "conflicting server name" в логах Nginx означает, что одно и то же доменное имя объявлено в двух разных конфигурационных файлах.
50. Ошибка "protocol options redefined" возникает, когда настройки SSL определены в нескольких блоках server для одного порта.
51. Ошибка "duplicate extension" в mime.types означает, что одно расширение файла определено дважды и не критична.
52. Для диагностики занятости порта используется команда sudo ss -tuln | grep <порт>.
53. Для определения процесса, занимающего порт, используется sudo lsof -i :<порт>.
54. Устаревший синтаксис listen ... http2 в Nginx рекомендуется заменить на отдельную директиву http2 on;.
55. Если после изменения портов в .env контейнер не запускается, нужно проверить, свободны ли эти порты.
56. При ручном исправлении конфига Nginx после Certbot, все настройки SSL должны быть только в блоке для порта 443.
57. Доступ к веб-интерфейсу по http://домен:8087 приведет к редиректу на HTTPS и может вызвать циклическую ошибку.
58. Доступ по https://домен:8443 работает напрямую к Mailcow, но с предупреждением о самоподписанном сертификате.
59. Прямой доступ к внутренним портам Mailcow следует использовать только для отладки.

PTR, DNS и репутация

60. PTR-запись связывает IP-адрес с доменным именем и критически важна для репутации почтового сервера.
61. PTR-запись настраивается у хостинг-провайдера, а не в DNS-зоне домена у регистратора.
62. Стандартные PTR от провайдера (например, 95-31-38-30.broadband.corbina.ru) вредят репутации почтового сервера.
63. Правильный PTR должен указывать на почтовый хостнейм (например, mail.other5.nbics.net).
64. Для идеальной работы необходима связка FCrDNS: PTR и A-запись должны указывать друг на друга.
65. Отсутствие правильного PTR — одна из главных причин попадания писем в спам.
66. Проверить PTR можно командой dig -x <IP-адрес> или на сайте mxtoolbox.com.
67. Если провайдер не дает настроить PTR, необходимо использовать внешний SMTP-релей или сменить хостера.
68. MX-запись должна указывать на почтовый хост (например, mail.other5.nbics.net), у которого есть A-запись.
69. Ошибка {No A Record} для MX-хоста — критична. Почта не будет доставляться.
70. SPF-запись (TXT) определяет, какие серверы имеют право отправлять почту от имени домена.
71. Проверить SPF можно на mxtoolbox.com или с помощью dig TXT домен.tld.
72. Пример правильной SPF-записи: v=spf1 mx a ip4:ВАШ_IP -all.
73. DKIM-запись — это цифровая подпись писем. Ключ генерируется в Mailcow и добавляется как TXT-запись.
74. DMARC-запись (TXT для _dmarc.домен.tld) определяет политику обработки писем, не прошедших SPF/DKIM.
75. Отсутствие DMARC-записи снижает доверие к домену и мешает внедрению BIMI.
76. Отчеты mxtoolbox показывают, что ваш IP не находится в черных списках (RBL) — это хороший знак.
77. Статус "Ok OK" для всех RBL означает чистую репутацию IP-адреса.
78. Домашние IP-адреса (из пулов Билайна, Ростелекома) непригодны для серьезного почтового сервера из-за PTR и блокировок портов.
79. IP от специализированных дата-центров (как dedic-center.ru) имеют лучшую исходную репутацию.

Управление и функциональность

80. В Mailcow по умолчанию нет самостоятельной регистрации пользователей.
81. Новые почтовые ящики создаются администратором в веб-интерфейсе (Mail Setup → Mailboxes).
82. Логин администратора по умолчанию: admin, пароль: moohoo.
83. При первом входе необходимо сменить пароль администратора.
84. Mailcow можно использовать как SMTP-сервер для внешних приложений (например, Element/Synapse).
85. Для этого создается специальный почтовый ящик (например, noreply@domain.tld), чьи данные указываются в настройках приложения.
86. При регистрации пользователя в стороннем сервисе, письмо подтверждения отправляется с этого спец-ящика на личную почту пользователя.
87. Такие транзакционные письма не считаются спамом при правильной настройке аутентификации домена (SPF, DKIM, DMARC).

Общие вопросы и сравнения

88. Установка почтового сервера — сложная задача, требующая знаний Linux, DNS и сетевых технологий.
89. Настройка правильных DNS-записей (A, MX, PTR, SPF, DKIM, DMARC) — самый важный и сложный этап.
90. Почтовый сервер состоит из нескольких компонентов: MTA (Postfix), MDA/IMAP (Dovecot), антиспам (Rspamd), веб-интерфейс (SOGo).
91. YunoHost — это простая платформа для хостинга приложений (включая почту), идеальна для новичков.
92. Mailcow — это профессиональное, мощное Docker-решение, сфокусированное только на почте.
93. Помимо Mailcow и YunoHost, существуют другие open-source решения: iRedMail, Mail-in-a-Box, Modoboa.
94. iRedMail — один из старейших и проверенных почтовых дистрибутивов.
95. Mail-in-a-Box нацелен на максимальную простоту и автоматизацию.
96. Modoboa — это гибкая панель управления для Postfix и Dovecot.
97. Выбор решения зависит от опыта и целей: YunoHost для хобби, Mailcow/iRedMail для бизнеса.
98. Для надежной корпоративной почты "из коробки" проще использовать Google Workspace или Microsoft 365.
99. Свой сервер требует постоянного мониторинга, обновлений и борьбы со спамом.
100. Самостоятельный почтовый сервер дает полный контроль над данными, но требует значительных временных затрат на поддержку.

[Admin]

Справочник по установке, настройке и эксплуатации Mailcow (Пункты 101–200)

Docker и управление контейнерами

101. docker compose exec <имя_контейнера> <команда> позволяет выполнить команду внутри работающего контейнера.
102. Пример: sudo docker compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} проверяет подключение к базе данных.
103. Контейнер nginx-mailcow выступает в роли обратного прокси внутри стека Mailcow для всех веб-сервисов.
104. Контейнер php-fpm-mailcow обрабатывает PHP-логику веб-интерфейса Mailcow.
105. Контейнер mysql-mailcow (MariaDB) хранит все настройки, домены, пользователей и пароли.
106. Контейнер dovecot-mailcow отвечает за доставку писем в ящики пользователей (IMAP/POP3).
107. Контейнер postfix-mailcow — это MTA (Mail Transfer Agent), принимающий и отправляющий почту.
108. Контейнер rspamd-mailcow — мощная система фильтрации спама и проверки писем.
109. Контейнер clamd-mailcow — антивирус, проверяющий вложения на вредоносный код.
110. Контейнер unbound-mailcow — локальный DNS-резолвер для повышения производительности и безопасности.
111. Контейнер redis-mailcow используется для кэширования и очередей задач.
112. Контейнер sogo-mailcow предоставляет веб-почту (Roundcube) и CalDAV/CardDAV функционал.
113. Контейнер acme-mailcow автоматически получает и обновляет SSL-сертификаты Let's Encrypt.
114. Контейнер watchdog-mailcow отслеживает состояние других контейнеров и перезапускает упавшие.
115. Контейнер netfilter-mailcow управляет правилами файервола внутри Docker-сети.

Проблемы с сетью и портами

116. Ошибка failed to bind host port for 0.0.0.0:443: address already in use означает, что порт 443 занят.
117. Для освобождения порта 443 нужно остановить сервис, который его занимает (nginx, apache, другой Docker-контейнер).
118. При использовании внешнего прокси порты 80 и 443 на хосте должны принадлежать прокси, а не Mailcow.
119. В этом случае в файле .env нужно указать альтернативные порты для Mailcow, например HTTP_PORT=8080 и HTTPS_PORT=8443.
120. Команда sudo ss -tulpn | grep 443 показывает все процессы, использующие порт 443 с их PID.
121. Если порт занят процессом с PID 1 (systemd), значит служба настроена на системном уровне.
122. После изменения портов в .env может потребоваться полный перезапуск: docker compose down && docker compose up -d.
123. Конфликт портов может возникнуть не только с внешними сервисами, но и с другими контейнерами Docker.
124. Для просмотра всех Docker-сетей используется команда docker network ls.
125. Для детальной информации о сети: docker network inspect <имя_сети>.
126. Стандартная сеть Docker bridge использует подсеть 172.17.0.0/16, что может конфликтовать с Mailcow.
127. Если несколько проектов Docker Compose используют одинаковые подсети, возникает конфликт.
128. Решение конфликта сетей — изменить IPV4_NETWORK в .env на уникальный диапазон.

Настройка внешнего Nginx (Reverse Proxy)

129. Внешний Nginx должен быть настроен на проксирование трафика на внутренние порты Mailcow.
130. Для HTTP-трафика: proxy_pass http://127.0.0.1:8080; (если HTTP_PORT=8080).
131. Для HTTPS-трафика: proxy_pass http://127.0.0.1:8080; также, так как SSL терминируется на внешнем Nginx.
132. Заголовок proxy_set_header X-Forwarded-Proto https; критически важен для правильной работы Mailcow за прокси.
133. Без этого заголовка Mailcow будет думать, что все запросы идут по HTTP, и пытаться редиректить на HTTPS.
134. Заголовок proxy_set_header Host $host; сохраняет оригинальное имя хоста при проксировании.
135. Заголовок proxy_set_header X-Real-IP $remote_addr; передает реальный IP-адрес клиента.
136. Для поддержки WebSocket (нужен SOGo для уведомлений) необходимы настройки:
     proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
137. Директива client_max_body_size 0; отключает ограничение на размер загружаемых файлов (важно для вложений).
138. В конфиге внешнего Nginx должен быть отдельный блок server для порта 80 с редиректом на HTTPS.
139. Редирект делается директивой return 301 https://$host$request_uri;.
140. Без этого редиректа пользователи, заходящие по HTTP, будут видеть ошибки или страницу Mailcow без стилей.

Certbot и SSL-сертификаты

141. Certbot — это клиент Let's Encrypt для автоматического получения и обновления SSL-сертификатов.
142. Команда sudo certbot --nginx автоматически получает сертификат и настраивает Nginx.
143. При первом запуске Certbot создает временный файл в /.well-known/acme-challenge/ для проверки домена.
144. Для этого порт 80 должен быть открыт и доступен из интернета.
145. Если Certbot находит существующий сертификат, он предлагает опции: переустановить или обновить.
146. Выбор 2: Renew & replace the certificate гарантирует получение свежего сертификата и обновление конфига.
147. Certbot автоматически добавляет в конфиг Nginx строки ssl_certificate и ssl_certificate_key.
148. Также добавляются include /etc/letsencrypt/options-ssl-nginx.conf; и ssl_dhparam....
149. Ошибка "We were unable to restart web server" означает, что Certbot не смог перезапустить Nginx из-за ошибок в конфиге.
150. В этом случае нужно исправить конфиг Nginx вручную и выполнить sudo certbot install --cert-name <домен>.
151. Сертификаты Let's Encrypt действительны 90 дней, Certbot автоматически их обновляет через cron/systemd timer.
152. После обновления сертификата Nginx перезагружается для применения новых сертификатов.

Диагностика и отладка

153. sudo docker compose logs -f <контейнер> позволяет следить за логами в реальном времени (аналог tail -f).
154. sudo docker compose logs --tail=50 mysql-mailcow показывает последние 50 строк логов MySQL.
155. Лог-сообщение mariadbd: ready for connections. означает, что MySQL готов к работе.
156. Циклическое повторение Waiting for SQL... в логах PHP-FPM указывает на проблемы с подключением к MySQL.
157. Ошибка connect() failed (111: Connection refused) в логах Nginx означает, что бэкенд (PHP-FPM) не отвечает.
158. Команда sudo docker compose restart <контейнер> перезапускает конкретный контейнер.
159. sudo docker compose restart nginx-mailcow перезапускает только Nginx, что полезно после изменения конфигов.
160. Проверка доступности порта изнутри контейнера: docker exec -it <контейнер> nc -zv 127.0.0.1 <порт>.
161. Для проверки DNS внутри контейнера: docker exec -it <контейнер> dig google.com.
162. Логирование ошибок PHP можно включить в конфигурации PHP-FPM, монтируя файл логов.
163. Все контейнеры Mailcow используют один и тот же внутренний часовой пояс из переменной TZ.

Настройка DNS и почтовые протоколы

164. Помимо веб-интерфейса, Mailcow использует стандартные почтовые порты: 25 (SMTP), 465 (SMTPS), 587 (Submission).
165. IMAP (для чтения почты) работает на портах 143 (STARTTLS) и 993 (SSL/TLS).
166. POP3 (устаревший протокол) работает на портах 110 и 995.
167. Sieve (для фильтрации почты) работает на порту 4190.
168. Для нормальной работы почты эти порты должны быть открыты в файерволе сервера.
169. Проверить доступность порта извне можно на mxtoolbox.com (Diagnostics -> SMTP Test).
170. При использовании внешнего прокси, почтовые порты должны быть открыты напрямую на сервере (прокси их не трогает).
171. SUBMISSION_PORT=587 в .env позволяет изменить стандартный порт для отправки почты клиентами.
172. SMTPS_PORT=465 — порт для устаревшего SMTPS (не путать с STARTTLS на порту 587).
173. IMAPS_PORT=993 и POP3S_PORT=995 — защищенные версии протоколов доступа к почте.
174. Для каждого добавленного почтового домена нужно настроить отдельные DNS-записи (MX, SPF, DKIM, DMARC).
175. DKIM-ключи генерируются отдельно для каждого домена в панели Mailcow.
176. Селектор DKIM по умолчанию в Mailcow — dkim (запись выглядит как dkim._domainkey.domain.tld).
177. DMARC-политика p=quarantine рекомендована для начальной настройки, p=reject — для полной защиты.
178. Адрес для DMARC-отчетов (rua=mailto:...) должен существовать и быть доступным.

Безопасность

179. Встроенный watchdog (USE_WATCHDOG=y) автоматически перезапускает упавшие контейнеры.
180. WATCHDOG_NOTIFY_EMAIL позволяет настроить отправку уведомлений о проблемах на email.
181. WATCHDOG_NOTIFY_BAN включает уведомления о забаненных IP-адресах.
182. WATCHDOG_EXTERNAL_CHECKS=n отключает внешние проверки на open relay (по умолчанию выключено).
183. Переменная SKIP_CLAMD=n включает антивирус ClamAV (рекомендуется, но требует ресурсов).
184. SKIP_SOGO=n включает веб-почту SOGo (рекомендуется оставить включенным).
185. SKIP_FTS=n включает полнотекстовый поиск в Dovecot (полезно, но нагружает сервер).
186. FTS_HEAP=128 ограничивает память для индексации писем (можно увеличить при наличии ресурсов).
187. FTS_PROCS=1 ограничивает количество процессов индексации (можно увеличить на мощных серверах).
188. ALLOW_ADMIN_EMAIL_LOGIN=n запрещает администраторам входить в почтовые ящики пользователей без пароля.
189. ACL_ANYONE=disallow запрещает создание общих папок для всех аутентифицированных пользователей.
190. ENABLE_SSL_SNI=n отключает поддержку отдельных сертификатов для разных доменов (если не нужно).
191. ENABLE_IPV6=false отключает IPv6 (если не настроен на сервере).

Почтовые ящики и квоты

192. MAILDIR_GC_TIME=7200 определяет время (в минутах) хранения удаленных ящиков в корзине (здесь 5 дней).
193. MAILDIR_SUB=Maildir — стандартное имя директории для хранения писем в формате Maildir.
194. SOGO_EXPIRE_SESSION=480 — время сессии в веб-почте SOGo в минутах (480 = 8 часов).
195. SOGO_URL_ENCRYPTION_KEY — ключ шифрования для URL в SOGo (генерируется автоматически).
196. DOVECOT_MASTER_USER и DOVECOT_MASTER_PASS — мастер-аккаунт для доступа к любым ящикам (использовать осторожно).
197. LOG_LINES=9999 — количество сохраняемых строк логов в Redis для каждого сервиса.
198. SPAMHAUS_DQS_KEY — ключ для Spamhaus Data Query Service (если ваш IP в заблокированной ASN).

API и автоматизация

199. Mailcow имеет полноценный REST API для управления доменами, ящиками, алиасами и настройками.
200. Для использования API нужно создать ключ в разделе Access → API и разрешить доступ с нужных IP (API_ALLOW_FROM).