Установка Flibusta-at-home шаг за шагом

Эта статья — пошаговый чеклист установки Flibusta-at-home в рекомендуемой конфигурации external_services: контейнер библиотеки подключается к уже существующим Postgres и reverse proxy (в примерах — SWAG, nginx с автоматическими сертификатами Let’s Encrypt). Если у Вас пока нет ни Postgres, ни reverse proxy — их придётся поднять, это отдельные, хорошо документированные контейнеры.

Когда уместна конфигурация all-in-one. В репозитории есть docs_and_configs/all_in_one_config/docker-compose.yml, который поднимает Postgres, nginx, Redis и библиотеку одним файлом. nginx там работает по HTTP без TLS, и раньше я называл эту конфигурацию просто устаревшей. Точнее так: важно, чтобы по HTTPS работал браузер читателя, а кто завершает TLS — вопрос отдельный. Если это делает внешний сервис (например Cloudflare Tunnel, см. статью о доступе из интернета), то all-in-one за туннелем — рабочая схема, и FLIBUSTA_ALLOW_ADMIN_ACCESS_BY_HTTP включать не нужно: браузер на https:// исправно возвращает cookie с атрибутом Secure. Второй допустимый случай — изолированная сеть или машина для разработки, которой сертификат взять негде; там флаг нужен, но и выставлять такую установку в интернет нельзя. В остальных случаях берите external_services — дальше статья именно про него.

Что понадобится

Что	Зачем
Linux-хост (NAS, мини-ПК, VPS) с Docker Engine и плагином `docker compose`	здесь будет работать контейнер
Postgres в Docker (любой современной версии)	база данных библиотеки; нужен доступ к административному аккаунту (обычно `postgres`) для первичного создания БД
Reverse proxy с HTTPS (SWAG, Nginx Proxy Manager, Caddy, Traefik…)	фронтенд: раздача статики и проксирование PHP на php-fpm
Диск под архивы книг	полный архив Флибусты занимает сотни гигабайт; можно держать только часть, см. статью о скачивании на лету
Доступ к зеркалу Флибусты с хоста	для скачивания дампов БД, обложек и ежедневных обновлений
(необязательно) Redis в Docker	хранение сессий и кэш; без него библиотека полностью работоспособна, см. статью о кэше

Ниже предполагается, что всё лежит в /opt/flibusta — замените на свой путь.

Шаг 1. Директории на хосте

Контейнеру нужны четыре точки монтирования:

На хосте	В контейнере	Назначение	Права
`/opt/flibusta/books`	`/flibusta` (только чтение)	zip-архивы книг Флибусты	чтение для uid 82
`/opt/flibusta/sql`	`/sql`	сюда скачиваются дампы БД	запись для uid 82
`/opt/flibusta/cache`	`/cache`	рабочие данные: обложки, локально скачанные книги, логи, статус операций	запись для uid 82
`/opt/flibusta/secrets`	`/run/secrets/*` (через Docker secrets)	файлы с паролями	чтение для uid 82

PHP в образе работает от пользователя www-data с uid 82 (это стандарт образа php:fpm-alpine). На хосте такого пользователя, скорее всего, нет — это нормально, права выдаются по числовому id:

sudo mkdir -p /opt/flibusta/{books,sql,cache,secrets}
sudo chown -R 82:82 /opt/flibusta/sql /opt/flibusta/cache
sudo chmod -R o+rX /opt/flibusta/books      # книги достаточно сделать читаемыми

Шаг 2. Архивы книг

Архивы Флибусты распространяются торрентами. Файлы называются по схеме f.fb2-000024-030559.zip (книги fb2), f.usr-…zip (остальные форматы: pdf, djvu, epub…) и f.n-…zip / f.fb2.…zip (новые поступления). Числа — диапазон идентификаторов книг внутри архива; именно по ним библиотека находит нужный файл. Положите архивы в /opt/flibusta/books как есть, не распаковывая.

На этом этапе можно ограничиться частью архива (например, только fb2) или даже пустой директорией — она обязана существовать, иначе контейнер завершится с ошибкой FATAL: directory /flibusta with books is not found. Торренты можно докачивать и позже, прямо из веб-интерфейса (раздел «Сервис», см. статью об административных разделах).

Шаг 3. Файлы с паролями (Docker secrets)

Нужны три файла:

Файл	Содержимое
`secrets/flibusta_pwd.txt`	пароль пользователя БД `flibusta` (будет создан автоматически)
`secrets/postgres_admin_pwd.txt`	пароль административного аккаунта Postgres (нужен только при первом запуске)
`secrets/flibusta_app_admin_pwd.txt`	пароль администратора библиотеки

Важно: в файле не должно быть перевода строки в конце. Docker передаёт файл побайтно, и символ \n станет частью пароля. Надёжный способ:

cd /opt/flibusta/secrets
printf '%s' 'СильныйПарольБД'      > flibusta_pwd.txt
printf '%s' 'ПарольАдминаPostgres'  > postgres_admin_pwd.txt
printf '%s' 'ПарольАдминаБиблиотеки' > flibusta_app_admin_pwd.txt
sudo chown 82:82 *.txt && sudo chmod 400 *.txt

Проверить, что переводов строки нет: wc -l flibusta_pwd.txt должен вернуть 0.

Шаг 4. Docker-сети

Библиотека общается с двумя соседями по двум отдельным сетям:

postgres_db_net — между библиотекой и Postgres;
flibusta_net — между библиотекой и reverse proxy. Шаблон nginx-конфига обращается к контейнеру по имени flibusta-fpm, поэтому в шаблоне docker-compose контейнеру задан фиксированный адрес; подсеть должна ему соответствовать.

docker network create postgres_db_net
docker network create --subnet 172.101.0.0/16 flibusta_net

Если Postgres уже подключён к какой-то сети — можно использовать её вместо postgres_db_net, тогда поправьте имя сети в docker-compose. Иначе подключите Postgres к новой сети: либо добавьте postgres_db_net в секцию networks его compose-файла (и объявите сеть как external: true), либо разово: docker network connect postgres_db_net <имя-контейнера-postgres>.

Шаг 5. docker-compose.yml библиотеки

Возьмите шаблон docs_and_configs/external_services_config/docker-compose.yml.template из репозитория и заполните плейсхолдеры (все переменные подробно разобраны в отдельной статье):

services:
  flibusta-fpm:
    image: blitvin/flibusta-at-home
    container_name: flibusta-fpm
    working_dir: /application
    restart: unless-stopped
    environment:
      - TZ=Europe/Moscow
      - FLIBUSTA_WEBROOT=            # пусто для https://flibusta.example.org, "/flibusta" для https://example.org/flibusta
      - FLIBUSTA_DBUSER=flibusta
      - FLIBUSTA_DBNAME=flibusta
      - FLIBUSTA_DBTYPE=postgres
      - FLIBUSTA_DBHOST=postgres     # имя контейнера Postgres
      - FLIBUSTA_DBPASSWORD_FILE=/run/secrets/FLIBUSTA_PWD
      - POSTGRES_ADMIN_DBPASSWORD_FILE=/run/secrets/POSTGRES_ADMIN_PWD
      - MAX_FB2_SIZE_2_DISPLAY=100000000
      - FLIBUSTA_APP_ADMIN=flibustadmin
      - FLIBUSTA_APP_ADMIN_PASSWORD_FILE=/run/secrets/FLIBUSTA_APP_ADMIN_PWD
      - FLIBUSTA_TRUSTED_NET=192.168.1.0/24
      - FLIBUSTA_URL=https://flibusta.is
      - FLIBUSTA_ENABLE_MISSING_BOOK_DOWNLOAD=true
      # Необязательно: сессии и кэш в Redis. Пока эта строка закомментирована,
      # сессии хранятся в Postgres и кэш не используется.
      # - FLIBUSTA_REDIS_HOST=redis
    networks:
      flibusta_net:
        ipv4_address: 172.101.0.101
      postgres_db_net:
    volumes:
      - /opt/flibusta/books:/flibusta:ro
      - /opt/flibusta/sql:/sql
      - /opt/flibusta/cache:/cache
      - flibusta_public_files:/public_mountpoint
    secrets:
      - FLIBUSTA_PWD
      - POSTGRES_ADMIN_PWD
      - FLIBUSTA_APP_ADMIN_PWD

secrets:
  FLIBUSTA_PWD:
    file: /opt/flibusta/secrets/flibusta_pwd.txt
  POSTGRES_ADMIN_PWD:
    file: /opt/flibusta/secrets/postgres_admin_pwd.txt
  FLIBUSTA_APP_ADMIN_PWD:
    file: /opt/flibusta/secrets/flibusta_app_admin_pwd.txt

networks:
  postgres_db_net:
    external: true
  flibusta_net:
    external: true

volumes:
  flibusta_public_files:

Про закомментированную строку FLIBUSTA_REDIS_HOST: библиотека умеет хранить сессии и кэш в Redis, и это заметно снижает нагрузку на базу. Для первой установки это лишняя движущаяся часть, поэтому начните без неё — включить Redis можно в любой момент позже, не трогая ничего другого. Что он даёт и как его добавить — в статье о кэше и производительности.

Обратите внимание на том flibusta_public_files. Nginx должен отдавать статику (JS-читалки, CSS, картинки) сам, минуя PHP, поэтому при каждом старте контейнер копирует содержимое application/public в этот именованный том, а reverse proxy монтирует его к себе. Docker Compose даёт тому имя с префиксом проекта: если compose-файл лежит в директории flibusta-at-home, том будет называться flibusta-at-home_flibusta_public_files. Уточнить можно командой docker volume ls после первого запуска.

Шаг 6. Подключение к reverse proxy (SWAG / nginx)

Есть два варианта адреса библиотеки:

subdomain — https://flibusta.example.org/. FLIBUSTA_WEBROOT пустой, шаблон конфига — flibusta.subdomain.conf, он кладётся в nginx/site-confs/ (или proxy-confs/, в зависимости от вашей сборки SWAG) как отдельный server {}.
subfolder — https://example.org/flibusta/. FLIBUSTA_WEBROOT=/flibusta, шаблон — flibusta.subfolder.conf, это блок location ^~ /flibusta, который нужно include-нуть внутрь основного server {} в site-confs/default.conf.

Оба шаблона лежат в docs_and_configs/external_services_config/. В compose-файл SWAG добавьте том со статикой и сеть библиотеки:

services:
  swag:
    # ...
    volumes:
      # ...
      - flibusta-at-home_flibusta_public_files:/srv/flibusta:ro
      - /opt/flibusta/nginx/flibusta.subdomain.conf:/config/nginx/site-confs/flibusta.subdomain.conf:ro
    networks:
      - flibusta_net
      # ... остальные сети SWAG

volumes:
  flibusta-at-home_flibusta_public_files:
    external: true

networks:
  flibusta_net:
    external: true

В самом конфиге проверьте три вещи: директиву root (в шаблоне статика ожидается в /srv/flibusta), имя upstream-контейнера (flibusta-fpm) и, для subdomain-варианта, что ваш сертификат покрывает поддомен (переменная SUBDOMAINS в SWAG или wildcard-сертификат) и что в DNS есть соответствующая запись.

Если Ваш reverse proxy не nginx (Caddy, Traefik, NPM), логика та же: статика отдаётся из тома, всё остальное уходит по FastCGI на flibusta-fpm:9000 с SCRIPT_FILENAME /application/public/$fastcgi_script_name. Полный список fastcgi_param, которые ожидает приложение (в частности REMOTE_ADDR, HTTP_X_FORWARDED_PROTO, HTTP_AUTHORIZATION для OPDS), есть в шаблонах.

Шаг 7. Первый запуск

cd /opt/flibusta   # где лежит docker-compose.yml
docker compose pull
docker compose up -d
docker compose logs -f flibusta-fpm

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

проверяет доступность FLIBUSTA_DBHOST;
если роли flibusta в Postgres нет — подключается административным аккаунтом и создаёт пользователя, базу, таблицы и индексы (tools/postgres_init.sql);
создаёт структуру /cache и пустой лог попыток входа;
синхронизирует статику в /public_mountpoint;
применяет миграции схемы (tools/postgres_migration.sql, лог в /cache/log/postgres_migration.log);
заводит администратора FLIBUSTA_APP_ADMIN, если его ещё нет;
строит индекс zip-архивов /cache/zip_index.php, если его нет (на первом запуске база пуста, так что индекс появится после «Сканирования ZIP»);
запускает php-fpm.

В логе должно быть Migration proceeded и Ensuring admin user … exists, без FATAL. Типичные проблемы на этом шаге: Postgres не в сети postgres_db_net (… is unreachable), у административного аккаунта нет прав CREATEDB/CREATEROLE, или пароль с переводом строки в конце.

После успешной инициализации административный пароль Postgres контейнеру больше не нужен — можно заменить содержимое postgres_admin_pwd.txt на что-нибудь заведомо неверное.

Перезапустите reverse proxy, чтобы он подхватил новый конфиг и том: docker restart swag (или docker exec swag nginx -s reload, если менялся только конфиг).

Шаг 8. Первый вход и наполнение базы

Откройте адрес библиотеки. Если Вы заходите из FLIBUSTA_TRUSTED_NET, форма входа не появится — библиотека пустит Вас как анонимного читателя. Для административных действий всё равно нужен вход: нажмите «Сменить пользователя» в правом верхнем углу и войдите под FLIBUSTA_APP_ADMIN.

Административные разделы доступны только по HTTPS. Если Вы видите предупреждение «соединение не защищено» — проверьте, что reverse proxy передаёт HTTP_X_FORWARDED_PROTO.

Дальше — раздел «Сервис», кнопки по порядку:

Скачать базу данных — скачивает дампы таблиц Флибусты в /sql (несколько сотен мегабайт).
Обновить базу данных — импортирует дампы в Postgres, чистит аннотации, строит полнотекстовые индексы и индекс zip-архивов. На время импорта библиотека переходит в режим техобслуживания; это занимает от нескольких минут до десятков минут в зависимости от железа.
Скачать обложки — архивы обложек книг и фотографий авторов.
Скачать последние обновления — ежедневные добавления Флибусты, которых ещё нет в Ваших торрент-архивах.
Сканирование ZIP — после любого изменения набора архивов в /flibusta или /cache/local.

Ход выполнения виден на той же странице; она обновляется автоматически.

Шаг 9. Пользователи

В разделе «Пользователи» создайте аккаунты для читателей (форма «Добавить/обновить пользователя»). Читатель без флага «админ» видит только книги, полку и свои настройки. Подробнее — в статье об административных разделах.

Шаг 10. Что настроить потом

Защиту от перебора паролей на уровне файрвола: fail2ban и ротация лога попыток входа.
Автоматическое обновление библиотеки по расписанию: сервисные скрипты и cron.
Доступ не только из дома: доступ к библиотеке из интернета.
Подключение читалок по OPDS: адрес каталога показан в разделе «Справка» самой библиотеки.
Снижение нагрузки на базу, если библиотекой пользуется вся семья: кэш и Redis.

Чеклист

Директории books, sql, cache, secrets созданы; sql и cache доступны на запись uid 82
Архивы книг (или хотя бы пустая директория) в books
Три файла паролей без \n в конце, права 400, владелец 82
Сети postgres_db_net и flibusta_net созданы; Postgres подключён к первой
docker-compose.yml заполнен: FLIBUSTA_DBHOST, FLIBUSTA_WEBROOT, FLIBUSTA_TRUSTED_NET, TZ, пути томов
Reverse proxy: том статики, сеть flibusta_net, конфиг subdomain/subfolder, сертификат и DNS
docker compose up -d, в логе нет FATAL
Reverse proxy перезапущен
Вход администратором по HTTPS, «Сервис»: скачать базу → обновить базу → обложки → обновления → скан ZIP
Созданы пользователи-читатели
Пароль администратора Postgres в секрете заменён на невалидный
(необязательно, можно позже) Поднят Redis и задан FLIBUSTA_REDIS_HOST

Что понадобится#

Шаг 1. Директории на хосте#

Шаг 2. Архивы книг#

Шаг 3. Файлы с паролями (Docker secrets)#

Шаг 4. Docker-сети#

Шаг 5. docker-compose.yml библиотеки#

Шаг 6. Подключение к reverse proxy (SWAG / nginx)#

Шаг 7. Первый запуск#

Шаг 8. Первый вход и наполнение базы#

Шаг 9. Пользователи#

Шаг 10. Что настроить потом#

Чеклист#