Isso в Docker Compose: готовый файл

MAATRIX

Статический сайт на Hugo, Jekyll или Eleventy собирается за секунды и не требует базы данных — но как только нужны комментарии под постами, приходится либо тащить чужой JavaScript-виджет с трекерами (Disqus), либо поднимать что-то своё. Isso — это «что-то своё» в самом компактном виде: один Python-процесс, SQLite вместо полноценной СУБД и JS-виджет весом в пару десятков килобайт, который просто встраивается в HTML-шаблон. Ниже — рабочий docker-compose.yml, с которым Isso поднимается за пять минут и требует минимум ресурсов на любом VPS.

Что такое Isso и когда он уместен

Isso написан на Python (Flask + gevent) и хранит все комментарии в одном SQLite-файле — никакого PostgreSQL или MySQL рядом не нужно. Это прямая противоположность Remark42 или Discourse, которые ждут отдельную базу и заметно больше памяти. За счёт этого Isso — почти идеальный выбор для блогов на статических генераторах: сам сайт не требует бэкенда, и странно было бы городить тяжёлую инфраструктуру ради комментариев под десятком постов.

Есть и обратная сторона: SQLite не расcчитан на высокую конкурентную нагрузку записи. Для блога с несколькими сотнями комментариев в месяц это не проблема, но для площадки с тысячами активных обсуждений в час лучше смотреть в сторону Remark42 (Go, тоже легковесный, но с более развитой модерацией) или Discourse (полноценный форум). Isso — это про простоту и минимализм, а не про масштаб.

Проект развивается медленно: последний релиз на PyPI выходит нечасто, и вокруг него не растёт огромное коммьюнити плагинов, как вокруг Disqus. Зато код маленький, зависимостей немного, и разобраться в нём при необходимости реально за вечер — что для self-hosted-решения на важном участке сайта скорее плюс, чем минус.

Структура проекта и Dockerfile

Официального образа Isso в Docker Hub от разработчиков нет, зато есть исходники на PyPI и в репозитории проекта, которые собираются в образ буквально в несколько шагов. Разложите каталоги так:

/opt/isso/
├── data/              # том с isso.db и служебными файлами
├── isso.cfg           # конфиг Isso
├── Dockerfile
└── docker-compose.yml

Dockerfile:

FROM python:3.12-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
        gcc libffi-dev libssl-dev \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir isso

RUN mkdir -p /config /db
VOLUME ["/config", "/db"]

EXPOSE 8080
CMD ["isso", "-c", "/config/isso.cfg", "run"]

gcc и заголовки нужны только на этапе сборки — часть зависимостей Isso (в первую очередь misaka для рендеринга Markdown) собирается из C-исходников через pip, готовых wheel-пакетов под все платформы нет. После установки эти пакеты можно было бы удалить отдельным этапом multi-stage сборки, но для VPS с несколькими гигабайтами диска экономия на паре десятков мегабайт не критична, а сборка проще.

Конфиг isso.cfg

Это ядро настройки — здесь задаётся домен сайта, база и политика модерации:

[general]
dbpath = /db/isso.db
host = https://vashdomen.ru/
notify = smtp
log-file = /dev/stdout

[server]
listen = http://0.0.0.0:8080/
reload = false

[smtp]
username = isso@vashdomen.ru
password = ваш_пароль_smtp
host = smtp.vashdomen.ru
port = 587
security = starttls
to = admin@vashdomen.ru
from = isso@vashdomen.ru

[moderation]
enabled = true
purge-after = 30d

[guard]
enabled = true
ratelimit = 2
direct-reply = 3
reply-to-self = false

[markup]
options = strikethrough, superscript, autolink
allowed-elements =
allowed-attributes =

Ключевые моменты:

• host — обязательно с реальным доменом и слешем в конце. Isso использует это значение для CORS-проверки Origin у запросов от JS-виджета — при несовпадении браузер получит 403 на попытку оставить комментарий, и разобраться в причине с первого взгляда непросто.
• [moderation] enabled = true — новые комментарии не публикуются сразу, а ждут подтверждения по ссылке из письма. Без настроенного SMTP модерация теряет смысл: письма просто некуда будет слать, а ссылки на подтверждение/удаление появятся только в логах.
• [guard] — встроенная защита от спама и накрутки: лимит комментариев в минуту с одного IP (ratelimit) и лимит ответов на один комментарий (direct-reply). Для публичного блога стоит держать оба значения по умолчанию или строже — Isso не имеет капчи из коробки, и это единственный барьер от простого флуда ботами.
• [markup] — Isso рендерит Markdown в комментариях через misaka; список options включает нужные расширения, а allowed-elements/allowed-attributes пустыми оставляет только базовый безопасный набор тегов после санитайзера.

Готовый docker-compose.yml

services:
  isso:
    build: .
    container_name: isso
    volumes:
      - ./isso.cfg:/config/isso.cfg:ro
      - isso-data:/db
    environment:
      - TZ=Europe/Moscow
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/')"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  isso-data:

Порт наружу намеренно не пробрасывается — Isso рассчитан на то, чтобы стоять за реверс-прокси на том же хосте, где крутится сам сайт. Запуск:

cd /opt/isso
docker compose up -d --build
docker compose logs -f isso

В логах при первом старте Isso создаст isso.db в томе isso-data и начнёт слушать 8080 внутри контейнера. Если сайт и Isso работают в разных compose-проектах, свяжите их общей внешней сетью (docker network create isso-net, и networks: - isso-net в обоих файлах) — это проще, чем публиковать порт 8080 на хост и открывать его наружу без необходимости.

Nginx как реверс-прокси перед Isso

Isso почти всегда живёт на том же домене, что и сам блог, но на отдельном пути — так JS-виджету не нужно думать о CORS вообще. Добавьте в конфиг сайта (тот же, что отдаёт статику Hugo или Jekyll) блок:

location /comments/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Isso периодически держит соединение открытым для long-polling новых комментариев
    proxy_read_timeout 90s;
}

Обратите внимание: путь в proxy_pass заканчивается слешем — это обрезает /comments/ из запроса перед передачей в Isso, который сам не знает про префикс /comments. Если контейнер стоит не на том же хосте, а порт 8080 вообще не публикуется наружу, добавьте вместо 127.0.0.1 внутренний IP или имя сервиса в общей Docker-сети. Общий принцип настройки реверс-прокси с SSL для таких связок подробно разобран в статье про Nginx как реверс-прокси — если предпочитаете автоматический выпуск сертификата без отдельного certbot, Caddy с авто-SSL закрывает тем же способом, что и для любого другого сервиса.

Встраивание виджета и перенос комментариев с Disqus

Со стороны генератора статики нужны две вещи: подключить JS Isso и разметить место под комментарии. В шаблон поста (например, layouts/partials/comments.html для Hugo) добавьте:

<section id="isso-thread"></section>
<script data-isso="/comments/"
        data-isso-css="true"
        data-isso-avatar="true"
        data-isso-vote="true"
        data-isso-reply-to-self="false"
        src="/comments/js/embed.min.js"></script>

data-isso указывает базовый путь — тот же, что настроен в location /comments/ выше. id="isso-thread" — обязательный якорь: именно в этот элемент виджет вставит форму и список комментариев после загрузки скрипта. Если на странице есть несколько разных URL под одним и тем же контентом (например, /post/ и /post/index.html), задайте явный идентификатор треда через data-isso-id, иначе Isso привяжет комментарии к location.pathname и они «разъедутся» между вариантами адреса.

Импорт из Disqus и миграция

Частый сценарий — переезд с Disqus, у которого есть удобный экспорт в WordPress-совместимый XML. Isso умеет импортировать его напрямую:

docker compose exec isso isso -c /config/isso.cfg import --type disqus /db/disqus-export.xml

Файл экспорта нужно сначала положить в volume — проще всего временно смонтировать локальную папку в контейнер или скопировать файл через docker cp:

docker cp disqus-export.xml isso:/db/disqus-export.xml
docker compose exec isso isso -c /config/isso.cfg import --type disqus /db/disqus-export.xml

Импорт сопоставляет комментарии с URL страниц по полю link из экспорта — если после переезда домен или структура путей изменились, часть тредов может не привязаться к нужным постам, и это стоит проверить вручную на нескольких страницах после импорта, а не полагаться, что всё перенеслось само.

Модерация, бэкап и обслуживание

Модерация в Isso — это письма со ссылками «одобрить» / «удалить» на каждый новый комментарий, без отдельной веб-панели администратора. Это осознанное упрощение проекта: для блога с несколькими комментариями в день почтового клиента достаточно, а лишний UI — лишняя поверхность для багов и атак.

Всё состояние Isso — это один файл isso.db в volume isso-data. Бэкап сводится к копированию этого файла (желательно с остановленным на момент копии контейнером или через sqlite3 .backup, чтобы не зацепить файл в момент записи):

docker compose exec isso sqlite3 /db/isso.db ".backup /db/isso-backup-$(date +%F).db"
docker cp isso:/db/isso-backup-$(date +%F).db ./backups/

Для регулярного автоматического бэкапа этот же volume можно подключить к отдельному контейнеру резервного копирования — подробная схема с расписанием и хранением версий описана в статье про restic в Docker Compose. Обновление самого Isso — пересборка образа без кэша, так как версия фиксируется через pip install isso на момент сборки:

docker compose build --no-cache isso
docker compose up -d

Частые вопросы