Гид по технологиям

Установка BookWyrm на Debian 12

• 7 min read • Инфраструктура • Обновлено 20 Nov 2025
BookWyrm на Debian 12: полная инструкция
BookWyrm на Debian 12: полная инструкция

Логотип BookWyrm на экране установки

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

Этот документ покрывает всё, что нужно для установки и базовой эксплуатации BookWyrm на Debian 12: системные зависимости, базы данных, кеши, веб-сервер, SSL, запуск сервисов и план резервного копирования. Подойдёт для небольшого инстанса (несколько сотен пользователей) и как отправная точка для более крупных развертываний.

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

Ключевые числа

  • Рекомендуемые ресурсы для небольшого инстанса: минимум 2 CPU ядра и 2 ГБ ОЗУ при включённых миниатюрах изображений. Для более комфортной работы — 4 CPU и 4–8 ГБ ОЗУ.
  • Порт по умолчанию для BookWyrm: 8000 (Gunicorn).
  • Порты Nginx: 80/443.

Примечания по терминологии

  • ActivityPub — протокол федерации для обмена активностями между инстансами.
  • FQDN — полное доменное имя (например, bookwyrm.example.com).
  • SSL/HTTPS — защищённое соединение, используемое Certbot/Let’s Encrypt.

Требования

  • Сервер с Debian 12.
  • Нераутовый пользователь с sudo.
  • FQDN, например bookwyrm.example.com, указывающий на IP сервера.
  • Учетная запись SMTP (Amazon SES, Mailgun или аналог) для отправки писем.
  • Базовые знания работы с терминалом и sudo.

Важно: все команды ниже выполняйте под подходящим пользователем или с sudo по мере необходимости.

Шаг 0 — Подготовьте систему

Обновите систему и установите базовые утилиты:

$ sudo apt update
$ sudo apt upgrade

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

$ sudo apt install wget curl nano ufw software-properties-common dirmngr apt-transport-https gnupg2 ca-certificates lsb-release debian-archive-keyring unzip -y

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

Шаг 1 — Настройка брандмауэра

Debian включает ufw (Uncomplicated Firewall). Сначала проверьте статус:

$ sudo ufw status

Если статус inactive, откройте SSH, HTTP и HTTPS, затем включите ufw:

$ sudo ufw allow OpenSSH
$ sudo ufw allow http
$ sudo ufw allow https
$ sudo ufw enable

Проверьте статус ещё раз:

$ sudo ufw status

Ожидаемый вывод покажет разрешённые правила для OpenSSH, 80 и 443.

Важно: при работе по SSH всегда сначала разрешайте OpenSSH, иначе вы потеряете подключение.

Шаг 2 — Установка и настройка PostgreSQL 15

BookWyrm использует PostgreSQL. Мы подключаем официальный репозиторий PostgreSQL и устанавливаем последнюю доступную версию (в инструкции — 15).

Добавьте ключ и репозиторий PostgreSQL:

$ curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /usr/share/keyrings/postgresql-key.gpg >/dev/null
$ sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/postgresql-key.gpg arch=amd64] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
$ sudo apt update
$ sudo apt install postgresql postgresql-contrib

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

$ sudo systemctl status postgresql

Создайте базу данных и пользователя:

$ sudo -i -u postgres psql
postgres=# CREATE DATABASE bookwyrm TEMPLATE template0 ENCODING 'UNICODE';
postgres-# CREATE USER bookwyrmuser WITH PASSWORD 'Your_Password';
postgres-# ALTER DATABASE bookwyrm OWNER TO bookwyrmuser;
postgres-# GRANT ALL PRIVILEGES ON DATABASE bookwyrm TO bookwyrmuser;
postgres-# \q

Проверьте подключение:

$ psql --username bookwyrmuser --password --host localhost bookwyrm

Если подключение успешно — переходите дальше.

Совет по безопасности: ограничьте доступ в /etc/postgresql/*/main/pg_hba.conf только локальными подключениями (local/127.0.0.1/::1) и используйте сильные пароли.

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

BookWyrm использует Redis для очередей и кеша. Установим современную версию из официального репозитория Redis.

$ curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
$ echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
$ sudo apt update
$ sudo apt install redis

Проверьте версию и подключение:

$ redis-server -v
$ redis-cli
127.0.0.1:6379> ping
PONG

Настройте надёжный пароль для Redis и включите аутентификацию. В интерактивной сессии redis-cli выполните:

127.0.0.1:6379> acl setuser default >Your_Redis_Password
127.0.0.1:6379> AUTH Your_Redis_Password
OK

Рекомендуется также в файле /etc/redis/redis.conf:

  • Установить bind 127.0.0.1 ::1
  • Включить protected-mode yes
  • Указать requirepass или управление через ACL

Не забудьте перезапустить службу после изменений.

Шаг 4 — Установка Nginx

Установите последнюю стабильную версию Nginx из официального репозитория:

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/debian `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
$ sudo apt update
$ sudo apt install nginx
$ sudo systemctl start nginx
$ sudo systemctl status nginx

При необходимости настройте серверные блоки и увеличьте server_names_hash_bucket_size в /etc/nginx/nginx.conf:

server_names_hash_bucket_size  64;

Шаг 5 — SSL с Certbot

Мы используем Certbot из snap для получения сертификатов Let’s Encrypt.

$ sudo apt install snapd
$ sudo snap install core && sudo snap refresh core
$ 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 certbot renew --dry-run

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

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

$ sudo mkdir /opt/bookwyrm
$ cd /opt/bookwyrm
$ sudo git clone https://github.com/bookwyrm-social/bookwyrm.git --branch production --single-branch ./
$ sudo cp .env.example .env

Шаг 7 — Конфигурация BookWyrm

Создайте секретный ключ и заполните .env. Пример генерации ключа:

$ openssl rand 60 | openssl base64 -A

Откройте .env для редактирования:

$ sudo nano .env

Пример заполненных переменных (локализовано):

SECRET_KEY="<сгенерированный_секрет>"
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

# включайте только если у сервера достаточно ресурсов
ENABLE_PREVIEW_IMAGES=true

Пояснения к основным переменным приведены в том же файле .env. Сохраните и закройте.

Важно: храните .env в безопасном месте и не публикуйте его в репозитории.

Шаг 8 — Настройка Nginx для BookWyrm

Скопируйте файл конфигурации, который поставляется с BookWyrm, и создайте собственный серверный блок:

$ sudo cp /opt/bookwyrm/nginx/server_config /etc/nginx/conf.d/server_config
$ sudo nano /etc/nginx/conf.d/bookwyrm.conf

Вставьте предложенный блок конфигурации (файл большой — см. оригинал). Он настраивает перенаправление с http на https, проксирование на Gunicorn (порт 8000), кеширование для анонимных пользователей и прямую отдачу статического контента.

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

$ sudo nginx -t
$ sudo systemctl restart nginx

Совет: для публичного инстанса добавьте дополнительные security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options) в блок server.

Шаг 9 — Установка BookWyrm (Python)

Установите Python-окружение и зависимости, выполните миграции и подготовьте статические файлы:

$ sudo apt install python3-venv python3-pip python3-dev libpq-dev
$ cd /opt/bookwyrm
$ sudo chown -R $USER:$USER .
$ python3 -m venv ./venv
$ ./venv/bin/pip3 install -r requirements.txt
$ venv/bin/python3 manage.py migrate
$ venv/bin/python3 manage.py initdb
$ venv/bin/python3 manage.py compile_themes
$ venv/bin/python3 manage.py collectstatic --no-input

Создайте системного пользователя и измените владельца каталога:

$ sudo useradd bookwyrm -r
$ sudo chown -R bookwyrm:bookwyrm /opt/bookwyrm

Запускайте дальнейшие команды от имени пользователя bookwyrm:

$ sudo -u bookwyrm echo I am the ${whoami} user

Шаг 10 — Сервисные файлы systemd

BookWyrm поставляется с unit-файлами для приложения, воркера и планировщика. Скопируйте их и включите сервисы:

$ sudo cp /opt/bookwyrm/contrib/systemd/*.service /etc/systemd/system/
$ sudo systemctl enable bookwyrm bookwyrm-worker bookwyrm-scheduler --now
$ sudo systemctl status bookwyrm

Получите код администратора для создания первой учётной записи:

$ sudo -u bookwyrm /opt/bookwyrm/venv/bin/python3 /opt/bookwyrm/manage.py admin_code

Сохраните код: он понадобится при первоначальной настройке через веб-интерфейс.

Шаг 11 — Доступ к веб-интерфейсу

Откройте в браузере:

https://bookwyrm.example.com

Следуйте мастеру: введите admin-код, создайте администратора, настройте сайт и политики. Проверьте отправку тестового письма в System → Email Configuration.

Экран создания администратора BookWyrm

Страница настроек сайта BookWyrm

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

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

BookWyrm включает утилиты резервного копирования, но они ориентированы на Docker. Для системной установки можно использовать простой скрипт резервного копирования и util для «подрезки» старых бэкапов.

Создайте скрипт резервного копирования ~/bookwyrm-backup.sh:

#!/bin/bash
POSTGRES_DB=bookwyrm
POSTGRES_USER=bookwyrmuser

if [ -z "$POSTGRES_DB" ]; then
    echo "Database not specified, defaulting to bookwyrm"
fi
if [ -z "$POSTGRES_USER" ]; then
    echo "Database user not specified, defaulting to bookwyrm"
fi

BACKUP_DB=${POSTGRES_DB:-bookwyrm}
BACKUP_USER=${POSTGRES_USER:-bookwyrm}
filename=backup_${BACKUP_DB}_$(date +%F)_$(date +%T)
PGPASSWORD="Your_Password" pg_dump -h localhost -U $BACKUP_USER $BACKUP_DB > ~/backups/$filename.sql

Сделайте скрипт исполняемым и создайте каталог для бэкапов:

$ sudo cp ~/bookwyrm-backup.sh /usr/local/bin/bookwyrm-backup.sh
$ sudo chmod +x /usr/local/bin/bookwyrm-backup.sh
$ mkdir ~/backups

Скопируйте утилиту для очистки старых бэкапов и настройте cron:

$ sudo cp /opt/bookwyrm/postgres-docker/weed.sh /usr/local/bin/bookwyrm-weed.sh
$ nano cronfile

Пример cronfile:

0 0 * * * /usr/local/bin/bookwyrm-backup.sh
# This script will weed the backups directory. It will keep the 14
# most-recent backups, then one backup/week for the next four backups, then one
# backup/month after that.
0 5 * * * /usr/local/bin/bookwyrm-weed.sh -d 14 -w 4 -m -1 ~/backups

Установите cron:

$ sudo cp ~/cronfile /etc/cron.d/cronfile
$ sudo chmod 0644 /etc/cron.d/cronfile
$ sudo crontab /etc/cron.d/cronfile
$ sudo touch /var/log/cron.log

Проверьте выполнение ручным запуском:

$ bookwyrm-backup.sh
$ ls ~/backups -al

Рекомендация: периодически переносите бэкапы на удалённое хранилище (S3, rsync на другой сервер) и шифруйте файлы, если там есть чувствительные данные.

Обновление BookWyrm

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

$ cd /opt/bookwyrm
$ sudo -u bookwyrm git pull
$ sudo -u bookwyrm venv/bin/pip install -r requirements.txt
$ sudo -u bookwyrm venv/bin/python3 manage.py compile_themes
$ sudo -u bookwyrm venv/bin/python3 manage.py collectstatic --no-input
# создайте бэкап перед миграцией
$ sudo -u bookwyrm venv/bin/python3 manage.py migrate
$ sudo systemctl restart bookwyrm bookwyrm-worker bookwyrm-scheduler

Краткая методология: всегда делайте бэкап БД и статических файлов перед миграцией.

Безопасность и жёсткая настройка

  • Redis: bind 127.0.0.1, protected-mode yes, используйте ACL/пароли.
  • PostgreSQL: закройте внешние подключения, используйте pg_hba.conf для строгой авторизации.
  • SSH: отключите root-логин, используйте key-based auth и ограничьте доступ по IP при необходимости.
  • fail2ban: установите и настройте для защиты SSH и Nginx.
  • Nginx: добавьте заголовки безопасности и включите HSTS для HTTPS.
  • Сертификаты: регулярно проверяйте автопродление Certbot.
  • Логи: настройте ротацию логов и мониторинг дискового пространства.

Пример security headers для Nginx:

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;

Когда установка может не сработать и как диагностировать

  1. Невозможно получить SSL-сертификат — проверьте, что DNS запись A/AAAA указывает на сервер и порт 80 не блокируется.
  2. Gunicorn не запускается — проверьте логи systemd: sudo journalctl -u bookwyrm -b и вывод venv/bin/python3 manage.py runserver для ошибок зависимостей.
  3. Ошибки подключения к PostgreSQL — проверьте POSTGRES_ переменные в .env и /etc/postgresql//main/pg_hba.conf.
  4. Redis не отвечает — проверьте bind, requirepass и что сервис активен: sudo systemctl status redis.
  5. Неправильные права на /opt/bookwyrm — убедитесь, что каталог принадлежит bookwyrm:bookwyrm.

Runbook: восстановление из резервной копии

  1. Остановите сервисы:
$ sudo systemctl stop bookwyrm bookwyrm-worker bookwyrm-scheduler
  1. Восстановите дамп PostgreSQL:
$ PGPASSWORD="Your_Password" psql -h localhost -U bookwyrmuser -d bookwyrm -f ~/backups/backup_bookwyrm_YYYY-MM-DD.sql
  1. При необходимости восстановите файлы /opt/bookwyrm/static и /opt/bookwyrm/images из бэкапа.
  2. Запустите сервисы и проверьте логи:
$ sudo systemctl start bookwyrm bookwyrm-worker bookwyrm-scheduler
$ sudo journalctl -u bookwyrm -f

Роли и контрольный список перед запуском

Системный администратор:

  • Настроить DNS и брандмауэр.
  • Установить Postgres, Redis, Nginx, Certbot.
  • Настроить автоматические бэкапы и мониторинг диска.

Разработчик/оператор BookWyrm:

  • Проверить .env и секреты.
  • Выполнить миграции и компиляцию тем.
  • Тестировать отправку почты и федерацию с другим инстансом.

Администратор сайта:

  • Создать админ-аккаунт через admin_code.
  • Настроить политику модерации и почтовые шаблоны.
  • Подтвердить работу регистрации и тестовых писем.

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

  • Страница https доступна и отвечает.
  • Пользователь админ создан и может войти.
  • Отправка тестового письма успешна.
  • Бэкап успешно создаётся по расписанию.
  • Сервисы bookwyrm*, nginx, postgresql, redis активны.

Диаграмма принятия решений (Mermaid)

flowchart TD
  A[Начать установку] --> B{DNS настроен?}
  B -- Да --> C{Доступ по SSH?}
  B -- Нет --> Z[Настроить DNS -> Перезапустить]
  C -- Да --> D[Настроить ufw, PostgreSQL, Redis, Nginx]
  C -- Нет --> Y[Проверить сеть SSH]
  D --> E{SSL получен?}
  E -- Да --> F[Клонировать BookWyrm и настроить .env]
  E -- Нет --> X[Проверить порты 80/443 и DNS]
  F --> G[Создать сервисы systemd и запустить]
  G --> H[Проверка: вход, почта, федерация]
  H --> I[Готово]

Краткий список команд для быстрого старта

  • Обновление системы: sudo apt update && sudo apt upgrade
  • Установка зависимостей: sudo apt install postgresql redis nginx python3-venv certbot snapd
  • Клонирование: sudo git clone https://github.com/bookwyrm-social/bookwyrm.git –branch production ./
  • Запуск миграций: venv/bin/python3 manage.py migrate
  • Включение сервисов: sudo systemctl enable –now bookwyrm bookwyrm-worker bookwyrm-scheduler

Глоссарий (1 строка)

  • ActivityPub — федеративный протокол обмена активностями между сайтами.
  • FQDN — полное доменное имя хоста (например, bookwyrm.example.com).
  • Certbot — инструмент для получения Let’s Encrypt сертификатов.

Заключение

Вы установили базовый рабочий инстанс BookWyrm на Debian 12. Дальше: настройте политику модерации, резервное копирование на удалённое хранилище и мониторинг сервисов. Для растущей аудитории рассмотрите выделение отдельного сервера для PostgreSQL и Redis.

Если остались вопросы — пишите в комментариях или в сообществе BookWyrm.

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

Поделиться: X/Twitter Facebook LinkedIn Telegram
Автор
Редакция

Похожие материалы

Несколько аккаунтов Skype: Multi Skype Launcher
Программное обеспечение

Несколько аккаунтов Skype: Multi Skype Launcher

Журнал для работы: повысить продуктивность
Productivity

Журнал для работы: повысить продуктивность

Персональные звуки уведомлений на Android
Android.

Персональные звуки уведомлений на Android

Скачивание шоу Hulu для офлайн‑просмотра
Стриминг

Скачивание шоу Hulu для офлайн‑просмотра

Microsoft Start: персонализированная новостная лента
Новости

Microsoft Start: персонализированная новостная лента

Как изменить имя в Epic Games быстро
Гайды

Как изменить имя в Epic Games быстро