Установка BookWyrm на Rocky Linux 9

BookWyrm — открытая федеративная социальная сеть для читателей, альтернатива Goodreads. В этой пошаговой инструкции показано, как развернуть BookWyrm на сервере с Rocky Linux 9: подготовить систему, установить Docker и Nginx, получить SSL через Certbot, сконфигурировать окружение и запустить контейнеры. В конце — резервное копирование, обновление и полезные методики поддержки.

Кому подходит этот гайд

Кратко: системным администраторам и энтузиастам, которые хотят самостоятельно запустить инстанс BookWyrm на VPS с Rocky Linux 9, используя Docker и Nginx в качестве внешнего обратного прокси. Требуются базовые навыки работы в терминале и доступ по sudo.

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

Логотип BookWyrm

BookWyrm — это открытая федеративная социальная сеть для любителей книг. Она предоставляет альтернативу Goodreads без рекламы, обменивается активностью через протокол ActivityPub и интегрируется с инстансами Mastodon и другими сервисами ActivityPub. В функционале — обзоры книг, рейтинги, статусы чтения, полки (to-read, currently-reading, read), списки книг, подписки на пользователей, а также инструменты модерации и гибкие настройки приватности.

Основные предпосылки

Сервер с Rocky Linux 9, минимум 2 ГБ оперативной памяти и 2 CPU. Для опции генерации превью-изображений требуется более мощный хост.
Неразвёрнутый (non-root) пользователь с правами sudo.
Полное доменное имя (FQDN), например bookwyrm.example.com, указывающее на сервер.
SMTP-аккаунт (Amazon SES, Mailgun или другой) для отправки служебной почты.
Обновите систему:

$ sudo dnf update

Установите необходимые пакеты:

$ sudo dnf install wget curl nano unzip yum-utils policycoreutils-python-utils -y

Некоторые пакеты могут уже быть установлены.

Чек-лист перед началом (SOP — краткий)

Зарезервирован FQDN и A/AAAA-записи у DNS-провайдера.
Открыты порты 80/443 во внешнем брандмауэре (или настроен внешний прокси).
Есть рабочий SMTP-аккаунт и доступ к его параметрам (хост, порт, логин, пароль).
На сервере установлены Docker, docker-compose и Git.
Убедитесь, что SELinux и firewall настроены или корректно учтены в инструкциях.

Шаг 1 — Настройка файервола (Firewalld)

Проверьте состояние firewalld:

$ sudo firewall-cmd --state
running

Список сервисов в зоне public:

$ sudo firewall-cmd --permanent --list-services

Разрешите HTTP и HTTPS:

$ sudo firewall-cmd --permanent --add-service=http
$ sudo firewall-cmd --permanent --add-service=https
$ sudo firewall-cmd --reload

Проверьте, что появились http и https в списке сервисов.

Шаг 2 — Установка Docker и Docker Compose

Добавьте официальный репозиторий Docker и установите пакеты:

$ sudo dnf install yum-utils
$ sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

$ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
$ sudo systemctl enable docker --now

Проверьте статус и добавьте пользователя в группу docker, чтобы не вводить sudo каждый раз:

$ sudo systemctl status docker
$ sudo usermod -aG docker $(whoami)

Выйдите и зайдите в систему снова, чтобы изменения вступили в силу.

Шаг 3 — Установка Git

$ sudo dnf install git
$ git --version

(Опционально) Настройте глобальные имя и email для git:

$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"

Шаг 4 — Установка Nginx (актуальная версия)

Rocky Linux может поставляться со старой версией, поэтому подключите официальный репозиторий Nginx:

$ sudo nano /etc/yum.repos.d/nginx.repo

Вставьте конфигурацию репозитория (как в оригинале), затем установите Nginx и запустите сервис:

$ sudo dnf install nginx
$ sudo systemctl enable nginx --now
$ sudo nginx -v

Проверьте статус службы:

$ sudo systemctl status nginx

Шаг 5 — SSL: установка Certbot через Snapd

Для получения сертификатов Let’s Encrypt используем Certbot в snap-пакете. Snapd требует репозитория EPEL:

$ sudo dnf install epel-release
$ sudo dnf install -y snapd
$ sudo systemctl enable snapd --now
$ sudo snap install core && sudo snap refresh core
$ sudo ln -s /var/lib/snapd/snap /snap
$ echo 'export PATH=$PATH:/var/lib/snapd/snap/bin' | sudo tee -a /etc/profile.d/snapd.sh
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot
$ certbot --version

Получение сертификата через nginx-плагин (пример):

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d bookwyrm.example.com

Сгенерируйте Diffie–Hellman параметры:

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Проверьте автообновление сертификата:

$ sudo systemctl list-timers
$ sudo certbot renew --dry-run

Important: для серверов с ограниченными ресурсами можно использовать внешние сервисы для выдачи сертификатов или доверять прокси, но убедитесь, что приватные ключи и права доступа защищены.

Шаг 6 — Скачивание BookWyrm

Создайте каталог и клонируйте production-ветку:

$ mkdir ~/bookwyrm
$ cd ~/bookwyrm
$ git clone https://github.com/bookwyrm-social/bookwyrm.git .
$ git checkout production
$ cp .env.example .env

Шаг 7 — Конфигурация файла окружения (.env)

Сгенерируйте секретный ключ:

$ openssl rand 60 | openssl base64 -A
kahYlt56TI2fZQwj0oX054u2aJE7bptHyInK4RXQadLLmXwGSDm8N1vW9uacA9N6FHoXPINPwOFTmnaT

Откройте .env для редактирования и заполните параметры (пример):

$ sudo nano .env

SECRET_KEY="kahYlt56TI2fZQwj0oX054u2aJE7bptHyInK4RXQadLLmXwGSDm8N1vW9uacA9N6FHoXPINPwOFTmnaT"
DOMAIN=bookwyrm.example.com
[email protected]
POSTGRES_PASSWORD=Your_Password
POSTGRES_USER=bookwyrmuser
POSTGRES_DB=bookwyrm
POSTGRES_HOST=localhost

REDIS_ACTIVITY_HOST=localhost
REDIS_ACTIVITY_PORT=6379
REDIS_ACTIVITY_PASSWORD=Your_Redis_Password
REDIS_ACTIVITY_DB_INDEX=0

REDIS_BROKER_HOST=localhost
REDIS_BROKER_PORT=6379
REDIS_BROKER_PASSWORD=Your_Redis_Password
REDIS_BROKER_DB_INDEX=1

FLOWER_USER=username
FLOWER_PASSWORD=flowerpassword

EMAIl_HOST=
EMAIL_PORT=587
EMAIL_HOST_USER=AmazonSESUSER
EMAIL_HOST_PASSWORD=AmazonSESPASSWORD
EMAIL_USE_TLS=true
EMAIL_USE_SSL=false
EMAIL_SENDER_NAME=HowtoForge
EMAIL_SENDER_DOMAIN=example.com

## only enable it if you have a fairly powered server with a minimum of 2 CPU Cores and 2GB of RAM
ENABLE_PREVIEW_IMAGES=true

Ключевые параметры:

SECRET_KEY — секрет Django.
DOMAIN — FQDN вашего инстанса.
POSTGRES_* — параметры БД (в docker-compose service обычно называется db).
REDIS_* — хост/порт/пароль и индексы баз для activity и broker.
FLOWER_* — учетные для Flower (Celery dashboard).
EMAIL_* — SMTP-параметры.
ENABLE_PREVIEW_IMAGES — включайте только на сервере с достаточными ресурсами.

Сохраните изменения.

Шаг 8 — Настройка docker-compose.yml для BookWyrm

Откройте docker-compose.yml и внесите изменения, если вы используете внешний Nginx как обратный прокси. В оригинальном файле часто идёт встроенный nginx и certbot — мы их отключаем и пробрасываем внутренний nginx на нестандартный порт (например 8001):

services:
  nginx:
    image: nginx:latest
    logging: *default-logging
    restart: unless-stopped
    ports:
    #  - "80:80"
    #  - "443:443"
      - "8001:8001"
    depends_on:
      - web
    networks:
      - main
    volumes:
      - ./nginx:/etc/nginx/conf.d
    #  - ./certbot/conf:/etc/nginx/ssl
    #  - ./certbot/data:/var/www/certbot
      - static_volume:/app/static
      - media_volume:/app/images
  #certbot:
  #  image: certbot/certbot:latest
  #  command: certonly --webroot --webroot-path=/var/www/certbot --email ${EMAIL} --agree-tos --no-eff-email -d ${DOMAIN} -d www.${DOMAIN}
    #command: renew --webroot --webroot-path /var/www/certbot
  #  logging: *default-logging
  #  volumes:
  #    - ./certbot/conf:/etc/letsencrypt
  #    - ./certbot/logs:/var/log/letsencrypt
  #    - ./certbot/data:/var/www/certbot

Сохраните файл.

Шаг 8 — Конфигурация Nginx (файлы внутри проекта и системный конфиг)

Скопируйте production-шаблон Nginx и отредактируйте default.conf, заменив your-domain.com на ваш DOMAIN и удалив блоки certbot, если вы используете внешний Certbot:

$ cp nginx/production nginx/default.conf
$ nano nginx/default.conf

Пример нужного блока reverse-proxy:

 server {
     listen [::]:8001;
     listen 8001;

     server_name bookwyrm.example.com;

     location / {
         proxy_pass http://web;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header Host $host;
         proxy_redirect off;
     }

     location /images/ {
         alias /app/images/;
     }

     location /static/ {
         alias /app/static/;
     }
 }

Создайте системный конфиг nginx в /etc/nginx/conf.d/bookwyrm.conf с пробросом на localhost:8001 и настройками SSL (пути к сертификатам Let’s Encrypt):

$ sudo nano /etc/nginx/conf.d/bookwyrm.conf

(вставьте конфиг как в оригинале с ssl_certificate указывающим на /etc/letsencrypt/live/bookwyrm.example.com/fullchain.pem и т.д.)

Добавьте server_names_hash_bucket_size 64 в /etc/nginx/nginx.conf перед include /etc/nginx/conf.d/*.conf;

Проверьте синтаксис и перезапустите nginx:

$ sudo nginx -t
$ sudo systemctl restart nginx

Notes: если у вас SELinux включён, добавьте необходимые правила или контекст для доступа Nginx к файлам сертификатов и проксируемым сокетам.

Шаг 9 — Установка BookWyrm (миграции и запуск)

Перейдите в каталог проекта и инициализируйте БД миграциями:

$ cd ~/bookwyrm
$ ./bw-dev migrate

Запустите сборку образов и контейнеры (это может занять 10–30 минут в зависимости от ресурсов):

$ docker compose up --build

После успешной сборки остановите процесс (Ctrl+C) и выполните первоначальную установку для получения кода администратора:

$ ./bw-dev setup

Вы получите одноразовый admin код, необходимый для создания аккаунта администратора. В любой момент код можно получить снова:

$ ./bw-dev admin_code

После этого запустите контейнеры в фоне:

$ docker compose up -d
$ docker ps

Шаг 10 — Первоначальная настройка через веб-интерфейс

Откройте https://bookwyrm.example.com. Вы пройдёте экран установки, введёте admin code и создадите учётную запись администратора.

Экран настройки BookWyrm

Заполните параметры сайта (Site Settings) и проверьте конфигурацию почты: System → Email Configuration, отправьте тестовое письмо.

Создание администратора BookWyrm

Настройки сайта BookWyrm

Страница конфигурации почты

Если тестовое письмо пришло — почта настроена корректно.

Тестовое письмо BookWyrm

Шаг 11 — Резервное копирование

BookWyrm поставляется со скриптом резервного копирования для Docker-окружения. Резервные дампы хранятся в каталоге /backups внутри контейнера базы.

Подключитесь в контейнер БД и проверьте содержимое:

$ docker exec -it bookwyrm-db-1 bash
$ ls backups -al
$ exit

Скопируйте резервную копию на хост:

$ docker cp bookwyrm-db-1:/backups

Чтобы включить автоматическое удаление старых бэкапов (pruning), отредактируйте ~/bookwyrm/postgres-docker/cronfile и раскомментируйте строчку с bookwyrm-weed.sh. По умолчанию предлагается хранить 14 последних бэкапов с политикой еженедельных и ежемесячных точек восстановления.

Шаг 12 — Обновление BookWyrm

Процедура обновления:

$ cd ~/bookwyrm
$ git pull
$ docker compose rebuild
$ docker compose run --rm web python manage.py migrate
$ docker compose run --rm web python manage.py compile_themes
$ docker compose run --rm web python manage.py collectstatic --no-input
$ docker compose down --remove-orphans
$ docker compose up -d

После обновления при необходимости восстановите или переполните потоки:

$ ./bw-dev populate_streams
# или
$ docker compose run --rm web python manage.py populate_streams

Если нужно удалить данные потоков:

$ docker compose run --rm web python manage.py erase_streams

Шаг 13 — Обзор командной утилиты bw-dev

Некоторые полезные команды bw-dev:

Подтвердить пользователю e-mail вручную:

$ ./bw-dev confirm_email

Сгенерировать превью-изображения (если ENABLE_PREVIEW_IMAGES=true):

$ ./bw-dev generate_preview_images --all

Сгенерировать миниатюры обложек:

$ ./bw-dev generate_thumbnails

Полный список опций смотрите в документации CLI внутри репозитория.

Практики безопасности и твики (Security hardening)

Ограничьте доступ к файлам сертификатов: права должны быть 600 для приватного ключа и владельцем root.
Настройте брандмауэр для ограничения административного доступа (SSH) только с доверенных IP.
Используйте fail2ban для защиты SSH и веб-панелей.
Регулярно обновляйте образы Docker и зависимости проекта.
Ограничьте ресурсы контейнеров (cpu/shares, memory) в docker-compose при необходимости.
Храните секреты (пароли, ключи) вне VCS — используйте секреты Docker или менеджер секретов.

Резервный план и откат (Incident runbook)

Проблема: сайт недоступен.
- Шаг 1: Проверить состояние контейнеров: docker ps
- Шаг 2: Проверить логи nginx и web: docker compose logs nginx web
- Шаг 3: Если проблема после обновления — откатить образ: docker compose down && git checkout HEAD@{1} && docker compose up -d
Проблема: ошибки миграции БД.
- Шаг 1: Остановить сервисы: docker compose down
- Шаг 2: Восстановить последнюю рабочую БД из /backups
- Шаг 3: Запустить контейнеры, проверить миграции локально и затем применить снова.
Проблема: почта не отправляется.
- Проверить параметры EMAIL_* в .env и логи celery/mail.
- Протестировать соединение с SMTP вручную: telnet smtp.host 587 или openssl s_client.

Мини-методология обслуживания (кратко)

Еженедельно: проверять логи, свободное место на диске, состояние контейнеров и очередь Celery.
Ежедневно: убедиться, что бэкапы создаются и копируются на удалённое хранилище.
При обновлениях: тестировать миграции на staging-боксе перед production.

Роли и чек-листы

Администратор сервера:

Настроить DNS и SSL.
Управлять бэкапами и обновлениями Docker-стека.

DevOps/Системный инженер:

Настроить мониторинг и оповещения (disk, cpu, memory, docker healthchecks).
Проводить обновления и откат при необходимости.

Контент-администратор сайта (не тех):

Настроить политики сайта, модерацию, шаблоны писем.
Проверить работоспособность уведомлений и подписок.

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

https://<ваш домен> открывается и сертификат действителен.
Администратор может войти и увидеть панель управления.
Тестовое письмо отправляется и приходит.
Все сервисы в docker-compose работают (web, celery, redis, db).

Когда этот подход может не подойти

Если вы используете систему с ограничениями на установку snapd/сервисы (например хостинг с кастомным образами).
Если необходима высокая доступность и автоматическое масштабирование — тогда стоит рассмотреть Kubernetes или управляемые сервисы баз данных и Redis.

Короткое руководство по диагностике (Test cases/acceptance criteria)

После deploy: сайт должен вернуть HTTP 200 на / и корректный заголовок Host.
Проверьте, что Celery работает и обрабатывает задания: docker compose logs celery_worker.
Отправка письма: System → Email Configuration → Send test email → сообщение должно прийти.

Decision tree для выбора SSL-решения

flowchart TD
  A[Нужен SSL?] -->|Да| B{Вы управляете сервером?}
  B -->|Да| C[Использовать Certbot на сервере 'snapd']
  B -->|Нет| D[Использовать прокси с SSL у хостера или внешние certs]
  A -->|Нет| E[Работа без SSL 'не рекомендуется']

Краткая глоссария (1-строчная)

ActivityPub — открытый протокол федерации для обмена активностью между сервисами.
Celery — система очередей задач (фоновые задания).
Flower — веб-интерфейс мониторинга Celery.
Redis — быстрый in-memory data store, используется для очередей и кэша.

Заключение

Эта инструкция покрывает полный цикл: подготовка сервера, установка Docker и Nginx, получение SSL, конфигурация окружения BookWyrm, запуск и базовые операции поддержки (бэкап, обновление). После запуска рекомендуется настроить мониторинг, регулярные резервные копии и тестирование обновлений на стенде.

Если остались вопросы — опишите проблему с логами и шагами воспроизведения, и сообщество или администраторы смогут помочь.

Summary

BookWyrm можно надёжно развернуть на Rocky Linux 9 с помощью Docker и внешнего Nginx.
SSL через Certbot (snap) и корректная конфигурация .env — ключевые шаги.
Резервное копирование и план отката обязательны перед обновлениями.
Для генерации превью-изображений потребуются более мощные ресурсы сервера.