Установка Listmonk на Ubuntu через Docker

О чём эта инструкция

Эта пошаговая инструкция объясняет, как установить и настроить Listmonk — лёгкую, самохостящуюся платформу для рассылок — на сервере Ubuntu, используя Docker и Docker Compose. Подойдёт для VPS с публичным доменом и A/PTR-записями. Включены советы по безопасности, отладке и интеграции с Gmail.

Ключевые понятия в одну строку:

• Listmonk — самохостинг-платформа для рассылок с шаблонами и аналитикой.
• Docker/Docker Compose — инструменты для контейнеризации и управления сервисами.
• Nginx — обратный прокси и точка терминатора HTTPS.
• Certbot — клиент Let’s Encrypt для автоматического получения SSL.

Содержание

• Преимущества Listmonk
• Предварительные требования
• Установка Docker и Docker Compose
• Развёртывание Listmonk с Docker Compose
• Настройка Nginx как обратного прокси
• Получение SSL-сертификата через Certbot
• Доступ, первоначальная настройка и подключение Gmail SMTP
• Безопасность и надёжность: рекомендации
• Отладка: частые ошибки и исправления
• Контрольные списки для ролей
• Критерии приёмки
• Краткое резюме

Преимущества Listmonk

• Лёгкий и быстрый: минималистичный стек, оптимизированный под высокую производительность.
• Гибкость доставки писем: можно использовать внешние SMTP-сервисы (например, Gmail) или собственный SMTP-сервер.
• Программируемые шаблоны писем: шаблон может подстраиваться под контекст пользователя.
• Встроенная аналитика: клики и просмотры по письмам и спискам.

Изображение: печатный заголовок “Newsletter” на старой пишущей машинке.

Предварительные требования

• VPS с Ubuntu (рекомендуется LTS), публичный IP.
• Домен с A-записью (и PTR по желанию) указывающий на VPS.
• Пользователь с правами sudo.
• Свободные порты: 80 и 443 для Nginx, 9000 для внутреннего доступа Listmonk.

В этой инструкции предполагается, что вы будете использовать Docker и Docker Compose для развёртывания.

Установка Docker и Docker Compose

1. Обновите систему и установите зависимости по безопасности:

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg lsb-release

2. Добавьте GPG-ключ Docker и репозиторий (корректные команды):

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

3. Создайте файл репозитория (замените “jammy” на вашу версию Ubuntu, если нужно):

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu jammy stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

4. Установите Docker Engine, Compose-плагин и вспомогательные утилиты:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-buildx-plugin nginx git curl

5. Добавьте своего пользователя в группу docker (замените <ваш_пользователь> на имя вашего аккаунта):

sudo usermod -aG docker <ваш_пользователь>

Примечание: выход из сессии и вход обратно или перезагрузка требуется, чтобы членство в группе вступило в силу.

Развёртывание Listmonk с Docker Compose

1. Создайте рабочую директорию:

mkdir -p ~/listmonk && cd ~/listmonk

2. Создайте конфигурационный файл приложения config.toml:

nano ./config.toml

Вставьте в файл (замените INSERT_RANDOM_PASSWORD_HERE реальным паролем для БД):

[app]
address = "0.0.0.0:9000"
admin_username = "listmonk"
admin_password = "listmonk"

[db]
host = "listmonk_db"
port = 5432
user = "listmonk"
password = "INSERT_RANDOM_PASSWORD_HERE"

database = "listmonk"

ssl_mode = "disable"
max_open = 25
max_idle = 25
max_lifetime = "300s"

params = ""

Совет: сгенерируйте пароль безопасно:

cat /dev/urandom | tr -dc 'A-Za-z0-9' | fold -w 32 | head -n 1

3. Создайте docker-compose.yml:

nano ./docker-compose.yml

Пример (адаптирован под таймзону):

version: "3.7"
x-app-defaults:
  restart: unless-stopped
  image: listmonk/listmonk:latest
  ports:
    - 9000:9000
  networks:
    - listmonk
  environment:
    - TZ=Asia/Manila
x-db-defaults:
  image: postgres:13
  ports:
    - 9432:5432
  networks:
    - listmonk
  environment:
    - POSTGRES_PASSWORD=INSERT_RANDOM_PASSWORD_HERE
    - POSTGRES_USER=listmonk
    - POSTGRES_DB=listmonk
  restart: unless-stopped
  healthcheck:
    test:
      - CMD-SHELL
      - pg_isready -U listmonk
    interval: 10s
    timeout: 5s
    retries: 6
services:
  db:
    image: postgres:13
    ports:
      - 9432:5432
    networks:
      - listmonk
    environment:
      - POSTGRES_PASSWORD=INSERT_RANDOM_PASSWORD_HERE
      - POSTGRES_USER=listmonk
      - POSTGRES_DB=listmonk
    restart: unless-stopped
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -U listmonk
      interval: 10s
      timeout: 5s
      retries: 6
    container_name: listmonk_db
    volumes:
      - type: volume
        source: listmonk-data
        target: /var/lib/postgresql/data
  app:
    restart: unless-stopped
    image: listmonk/listmonk:latest
    ports:
      - 9000:9000
    networks:
      - listmonk
    environment:
      - TZ=Asia/Manila
    container_name: listmonk_app
    depends_on:
      - db
    volumes:
      - ./config.toml:/listmonk/config.toml
networks:
  listmonk: null
volumes:
  listmonk-data: null

4. Запустите только базу данных, чтобы инициализировать том БД:

docker compose up -d db

5. Выполните начальную установку Listmonk (запуск скрипта установки внутри контейнера):

docker compose run --rm app ./listmonk --install

Когда установщик спросит о очистке базы данных, подтвердите (наберите Y).

6. Перезапустите все контейнеры:

docker compose up -d app db

Настройка Nginx как обратного прокси

Чтобы Listmonk был доступен извне по домену и под защитой HTTPS, используйте Nginx в качестве обратного прокси.

1. Создайте конфигурацию сайта:

sudo nano /etc/nginx/sites-available/listmonk

Пример конфигурации (замените listmonk.myvpsserver.top на ваш домен):

server {
    server_name listmonk.myvpsserver.top;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }
}

2. Активируйте сайт и перезагрузите Nginx:

sudo ln -s /etc/nginx/sites-available/listmonk /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Проверьте, что порт 80 открыт в фаерволе (ufw, iptables и т.п.).

Получение SSL-сертификата (Let’s Encrypt / Certbot)

1. Установите snapd/core (если ещё не установлен):

sudo snap install core

2. Установите certbot через snap и получите сертификат для Nginx-плагины:

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

3. Зарегистрируйте учетную запись Certbot (замените e-mail):

sudo certbot register --agree-tos -m you@your-email.invalid

4. Получите и установите сертификат для вашего домена (замените домен):

sudo certbot --nginx -d listmonk.myvpsserver.top

Certbot предложит автоматически настроить перенаправление HTTP→HTTPS и настроить конфигурацию Nginx.

Автопродление: certbot создает systemd таймер/cron. Проверьте работу планировщика:

sudo systemctl status snap.certbot.renew.timer
sudo certbot renew --dry-run

Доступ и базовая конфигурация Listmonk

Откройте в браузере https://listmonk.myvpsserver.top (замените домен). По умолчанию учётные данные, если вы не меняли config.toml, — admin: listmonk / listmonk. Обязательно смените пароль сразу же.

1. Войдите как администратор.
2. Откройте Settings → General и установите Root URL — полный адрес вашего инстанса (https://…). Сохраните.

Примечание: не забывайте изменить учётные данные администратора и использовать сложные пароли.

Подключение Gmail (SMTP) к Listmonk

Если вы хотите отправлять письма через Gmail, используйте «Пароли приложений» для аккаунтов с включённой двухфакторной аутентификацией.

1. В аккаунте Google: Кликните иконку пользователя → Управление аккаунтом Google → Безопасность → 2-Step Verification (включите, если не включён).

2. Включите 2-Step Verification, затем в разделе «App passwords» создайте новый пароль для приложения, назовите его “listmonk” и сохраните 16-символьный код.

3. В Listmonk: Settings → SMTP, в шаблоне Gmail выберите “Gmail” как шаблон, введите полный адрес Gmail в поле Username и 16-символьный App password (без пробелов) в поле Password. Сохраните.

4. В Settings → General укажите Default ‘from’ address как ваш Gmail-адрес.

Создание первой рассылки и списка

1. Dashboard → Lists → All lists → New.

2. Нажмите New, заполните название списка, тип (Public/Private), описание и сохраните.

3. Создайте кампанию (Campaign), выберите шаблон, настройте контент, сегменты и отправьте тестовую рассылку.

Безопасность и надёжность (рекомендации)

• Обновления: регулярно обновляйте образы Docker и систему (docker pull, docker compose pull и apt update/upgrade).
• Резервные копии: делайте бэкапы тома Postgres (pg_dump, или снимки тома).
• Фаервол: закройте все ненужные порты, разрешите 80/443, доступ по SSH ограничьте по IP и используйте ключи.
• Fail2ban/SSH-hardening: включите fail2ban для защиты от грубых атак.
• SSL: автоматическое продление certbot и проверка cron/task.
• Email deliverability: настроьте SPF, DKIM и DMARC в DNS для домена отправителя (особенно если не используете Gmail). Это улучшит доставляемость и защитит репутацию домена.
• Мониторинг: настройте простую систему оповещений (Prometheus/Pushgateway, или внешние сервисы) для состояния контейнеров и метрик Postgres.

Отладка: частые ошибки и исправления

• Приложение недоступно после запуска контейнеров:
  • Проверьте docker compose ps и логи docker compose logs app.
  • Убедитесь, что контейнер Listmonk слушает на 9000 (внутри) и проброшен наружу.
• Ошибка подключения к БД:
  • Проверьте переменные окружения POSTGRES_USER/PASSWORD и совпадение с config.toml.
  • docker compose logs db покажет состояние Postgres и healthcheck.
• Certbot не может проверить домен:
  • Убедитесь, что A-запись домена указывает на IP сервера и порт 80 доступен извне.
• Почта не отправляется через Gmail:
  • Проверьте правильность App password и Username.
  • Посмотрите логи Listmonk для ошибок SMTP (Settings → SMTP → test log) и системные логи.

Контрольные списки (роль-ориентированные)

Администратор (sysadmin):

• Настроен пользователь с sudo и доступом по SSH-ключам.
• Образ Docker и контейнеры обновлены.
• Настроены бэкапы Postgres и конфигурации.
• Проверено автоматическое продление сертификатов.

DevOps/Developer:

• Docker Compose корректно монтирует config.toml.
• CI/CD-процессы для обновления образов настроены (опционально).
• Мониторинг и логирование подключены.

Маркетинг/Контент:

• Создан список рассылки и тестовая рассылка.
• Настроены шаблоны писем и тесты в разных почтовых клиентах.
• Установлены политики отписки и GDPR-совместимые формы подписки.

Критерии приёмки

Чтобы считать установку выполненной, выполните эти проверки:

• Сайт доступен по HTTPS по заданному домену.
• Войти в Listmonk можно с изменёнными admin-учётными данными.
• Отправка тестового письма через SMTP проходит без ошибок.
• Резервное копирование БД успешно создаёт дамп.
• Certbot успешно прошёл dry-run продления сертификата.

Дополнительные подходы и альтернативы

• Развёртывание без Docker: можно установить Listmonk нативно на хостовую систему, но это потребует ручной установки зависимостей и сервиса systemd.
• Использование стороннего SMTP-провайдера: SendGrid, Mailgun или Amazon SES дают лучшие показатели доставляемости и масштабируемость.
• Использование управляемого PostgreSQL (например, облачный сервис): упрощает бэкапы и масштабирование, но повышает стоимость.

Мини-методология развёртывания (чекпойнты)

1. Подготовка сервера и домена (DNS).
2. Установка Docker и Compose.
3. Развёртывание Postgres и Listmonk, проверка доступа.
4. Настройка Nginx и тест по HTTP.
5. Получение SSL и переключение на HTTPS.
6. Настройка SMTP и тестовая рассылка.
7. Документирование и бэкапы.

Короткая галерея крайних случаев

• Если вы используете корпоративный SMTP с ограничениями по количеству писем — проверьте лимиты и отлавливайте bounce/ошибки.
• При частых перезапусках контейнера проверьте ресурсы VPS (память/CPU) и настройки Postgres (connection limits).

1‑строчный глоссарий

• VPS — виртуальный приватный сервер.
• SMTP — протокол отправки почты.
• SPF/DKIM/DMARC — DNS-записи для защиты и репутации почты.
• Certbot — клиент для автоматического получения сертификатов Let’s Encrypt.

Примеры тестов и приёмки (Acceptance)

• Тест 1: Открыть https://ваш-домен и убедиться в наличии зелёного замка SSL.
• Тест 2: Отправить тестовое письмо на личный адрес и проверить доставку в основной/спам-папку.
• Тест 3: Сделать дамп БД pg_dump и восстановить на тестовой машине.

Риски и смягчение

• Риск: утечка учётных данных. Смягчение: храните секреты вне репозитория, используйте менеджеры секретов или переменные окружения, ограничьте доступ.
• Риск: блокировка почты домена. Смягчение: настройка SPF/DKIM/DMARC и использование проверенного провайдера SMTP для массовых рассылок.

Примеры команд обслуживания

Обновление образов и перезапуск:

docker compose pull && docker compose up -d --remove-orphans

Просмотр логов сервиса:

docker compose logs -f app

Создание дампа Postgres (на работающей машине):

docker compose exec db pg_dump -U listmonk listmonk > ~/listmonk-backup-$(date +%F).sql

Итог / Резюме

• Listmonk — удобное решение для самохостинга рассылок, лёгкое в установке через Docker.
• Важные шаги: правильная настройка конфигурации, обратный прокси, SSL, SMTP и безопасность.
• Следуйте контрольным спискам и делайте бэкапы.

Краткий совет: если ожидается большой объём рассылок, заранее планируйте инфраструктуру доставки почты и настройку SPF/DKIM/DMARC.

Image credit: Newsletter – written on an old typewriter by 123RF. All alterations and screenshots by Ramces Red.