Всё поведение контейнера Flibusta-at-home настраивается через environment в docker-compose.yml. Эта статья — справочник по каждой переменной, а также по секциям secrets, volumes и networks шаблона docs_and_configs/external_services_config/docker-compose.yml.template.

Общие

Переменная По умолчанию Значение
TZ не задана (UTC) Часовой пояс контейнера, например Europe/Moscow. Влияет на время в логах, на отметки времени операций в разделе «Сервис» и на лог попыток входа. Если Вы используете fail2ban на хосте, TZ контейнера должен совпадать с часовым поясом хоста, иначе fail2ban будет неверно оценивать возраст записей.
FLIBUSTA_WEBROOT пусто Префикс пути, под которым библиотека доступна снаружи. Для https://flibusta.example.org/ оставьте пустым; для https://example.org/flibusta/ укажите /flibusta (со слэшем в начале, без слэша в конце). Используется при формировании всех ссылок и пути cookie сессии, поэтому должен точно совпадать с location в конфиге reverse proxy.
FLIBUSTA_APP_ROOT /application Внутренний путь к коду приложения. Менять не нужно.
FLIBUSTA_DEBUG_DB не задана Со значением true контейнер пишет в лог по строке на каждый запрос: dbstats <адрес> connected=<0/1> statements=<число> — открывалось ли соединение с базой и сколько запросов выполнено. Диагностическая переменная; в обычной работе держать выключенной, она пишет строку на каждую картинку.

База данных

Переменная По умолчанию Значение
FLIBUSTA_DBTYPE postgres Тип СУБД. Поддерживается только Postgres; любое другое значение игнорируется с записью в лог.
FLIBUSTA_DBHOST postgres Имя хоста Postgres. В Docker это имя контейнера (или сервиса), доступное по общей сети postgres_db_net. При старте контейнер пингует этот хост несколько раз (DB_HOST_PINGS, по умолчанию 3) и завершается, если он недоступен.
FLIBUSTA_DBNAME flibusta Имя базы данных. Создаётся автоматически при первом запуске.
FLIBUSTA_DBUSER flibusta Пользователь БД. Создаётся автоматически при первом запуске; именно его наличие служит признаком того, что инициализация уже прошла.
FLIBUSTA_DBPASSWORD_FILE — Путь к файлу с паролем FLIBUSTA_DBUSER, обычно /run/secrets/FLIBUSTA_PWD. Рекомендуемый способ.
FLIBUSTA_DBPASSWORD flibusta Пароль открытым текстом. Используется, только если файл не задан или не существует. Не используйте в продакшене.
POSTGRES_ADMIN_USER postgres Административный аккаунт Postgres, от имени которого создаются роль и база. Нужен только при первом запуске (или после удаления роли).
POSTGRES_ADMIN_DBPASSWORD_FILE — Файл с паролем административного аккаунта, обычно /run/secrets/POSTGRES_ADMIN_PWD. После успешной инициализации содержимое файла можно заменить на заведомо неверное — контейнер к нему больше не обращается.
DB_HOST_PINGS 3 Сколько раз пытаться достучаться до FLIBUSTA_DBHOST при старте (с паузой в секунду). Увеличьте, если Postgres стартует медленнее библиотеки.

Администратор библиотеки

Переменная По умолчанию Значение
FLIBUSTA_APP_ADMIN не задана Имя учётной записи администратора. При каждом старте контейнер проверяет, существует ли такой пользователь, и создаёт его, если нет. Существующий пользователь не трогается — сменить пароль через эту переменную нельзя.
FLIBUSTA_APP_ADMIN_PASSWORD_FILE — Файл с паролем администратора, обычно /run/secrets/FLIBUSTA_APP_ADMIN_PWD.
FLIBUSTA_APP_ADMIN_PASSWORD — Пароль открытым текстом; используется, если файл не задан.

Отсюда следует рецепт восстановления доступа, если пароль администратора забыт: задайте новое имя в FLIBUSTA_APP_ADMIN и новый пароль, перезапустите контейнер, войдите новым администратором и смените пароль или удалите старую учётную запись в разделе «Пользователи».

Доступ и безопасность

Переменная По умолчанию Значение
FLIBUSTA_TRUSTED_NET пусто Один IPv4-адрес или одна подсеть в CIDR-нотации (192.168.1.0/24, 10.0.0.0/8, 172.16.4.1), из которой читать книги можно без входа. Административные разделы всё равно требуют входа. Указать несколько подсетей нельзя. Некорректное значение игнорируется с сообщением в лог контейнера. Клиентам из доверенной сети выдаётся годовая cookie сессии вместо четырёхчасовой.
FLIBUSTA_ALLOW_ADMIN_ACCESS_BY_HTTP false Разрешить административные разделы по HTTP. Заодно снимает флаг Secure с cookie сессии и cookie «запомнить меня»: иначе браузер просто не вернул бы их по HTTP, сессия не сохранялась бы и форма входа появлялась бы снова и снова. Предназначено для отладки в изолированной сети и для onion-адресов; в обычной установке оставьте выключенной и используйте HTTPS. В версиях до исправления этой связки переменная не работала — Secure выставлялся безусловно, и войти по HTTP было невозможно.
MAX_FB2_SIZE_2_DISPLAY 100000000 Максимальный размер fb2-файла (в байтах), который библиотека рендерит в браузере; книги больше этого порога предлагаются только для скачивания. Значения меньше 1 000 000 игнорируются.

Важное замечание про FLIBUSTA_TRUSTED_NET за reverse proxy: библиотека видит адрес клиента в REMOTE_ADDR, который ей передаёт nginx через fastcgi_param. Если reverse proxy стоит за ещё одним прокси или туннелем (Cloudflare, Tailscale, VPN), убедитесь, что в REMOTE_ADDR попадает настоящий адрес клиента, а не адрес туннеля — иначе либо «доверенными» окажутся все, либо никто.

Флибуста и скачивание на лету

Переменная По умолчанию Значение
FLIBUSTA_URL https://flibusta.is Базовый адрес зеркала Флибусты. Используется для скачивания дампов БД (/sql/…), обложек, ежедневных обновлений (/daily/) и книг на лету (/b/<id>/<формат>). Если основной домен недоступен, укажите другое зеркало.
FLIBUSTA_ENABLE_MISSING_BOOK_DOWNLOAD true Скачивать ли отсутствующую локально книгу с FLIBUSTA_URL в момент, когда читатель её открывает. Обратите внимание: режим выключается только строкой false; любое другое значение (в том числе 0, no или опечатка) означает «включено». Подробнее — в статье о скачивании на лету.
FLIBUSTA_LOCAL_DUPLICATE_POLICY keep_both Что делать, если книга, добавленная вручную через раздел «Добавить», позже появляется в дампе Флибусты. keep_both — оставить обе; prefer_dump — удалить локальную копию, перенеся избранное и позицию чтения на книгу из дампа.

Если FLIBUSTA_URL или FLIBUSTA_ENABLE_MISSING_BOOK_DOWNLOAD не заданы, контейнер при старте пишет предупреждение в лог и использует значения по умолчанию.

Кэш и сессии (Redis)

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

Переменная По умолчанию Значение
FLIBUSTA_REDIS_HOST не задана Имя хоста Redis (обычно имя контейнера в общей сети Docker). Ключевая переменная: пока она пуста, ни кэш, ни хранение сессий в Redis не используются. Как только задана, Redis становится обязательным компонентом: при его недоступности библиотека отвечает 503, а не откатывается молча на Postgres.
FLIBUSTA_REDIS_PORT 6379 Порт Redis.
FLIBUSTA_REDIS_DB 0 Номер базы внутри Redis. Пригодится, если тот же экземпляр обслуживает и другие приложения.
FLIBUSTA_REDIS_PREFIX flibusta: Префикс всех ключей. Вторая линия обороны при общем экземпляре Redis: два разных префикса не мешают друг другу даже в одной базе.
FLIBUSTA_REDIS_PASSWORD_FILE — Файл с паролем Redis (requirepass), например /run/secrets/FLIBUSTA_REDIS_PWD. Нужен, только если Redis доступен за пределами доверенной сети.
FLIBUSTA_REDIS_PASSWORD — Пароль открытым текстом; используется, если файл не задан.
FLIBUSTA_SESSION_TRUSTED_TTL 2592000 (30 дней) Сколько секунд сессия клиента из доверенной сети живёт в Redis без обращений. Отсчёт обновляется при каждом запросе, так что регулярно используемое устройство не разлогинивается никогда. Для клиентов вне доверенной сети срок фиксирован — 4 часа, столько же, сколько живёт cookie.

Про FLIBUSTA_REDIS_PREFIX есть важная деталь: ключи без срока жизни (счётчик поколения кэша и ключ подписи) намеренно не имеют TTL, поэтому запускать Redis нужно с политикой вытеснения volatile-lru, а не allkeys-lru — иначе эти два ключа могут быть вытеснены вместе с остальными, и библиотека начнёт отдавать описания книг из предыдущего дампа. Рекомендуемая командная строка целиком:

redis-server --save "" --appendonly no --maxmemory 128mb --maxmemory-policy volatile-lru

Секция secrets

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

Каждый секрет монтируется в контейнер как файл /run/secrets/<ИМЯ>; именно эти пути указываются в переменных *_FILE. Требования к файлам: одна строка без перевода строки в конце, права на чтение для uid 82 (chown 82, chmod 400). Тот же uid 82 нужен потому, что PHP читает секреты уже после понижения привилегий до www-data.

Секция volumes

Том Точка в контейнере Замечания
директория с архивами книг /flibusta:ro Только чтение — библиотека никогда не пишет в архивы. Должна существовать, даже если пуста. Читаема для uid 82.
директория дампов /sql Сюда getsql.sh скачивает lib.*.sql.gz; при импорте они распаковываются на месте. Запись для uid 82.
рабочая директория /cache Обложки (covers/, authors/), книги, скачанные на лету и ежедневные обновления (local/), логи (log/), лог попыток входа (login_attempts/), файл статуса операций (status), блокировки (locks/), ETag-кэш (etag/). Запись для uid 82. Это единственная директория, которую имеет смысл бэкапить вместе с БД.
flibusta_public_files /public_mountpoint Именованный том со статикой для reverse proxy. Контейнер перезаписывает его при каждом старте (rsync --delete), так что руками туда ничего класть не надо.

Секция networks

Сеть Назначение
postgres_db_net Общая с контейнером Postgres. Объявлена как external: true — создаётся заранее (docker network create) и в неё же подключается Postgres.
flibusta_net Общая с reverse proxy. Контейнеру задан фиксированный ipv4_address (в шаблоне 172.101.0.101 в подсети 172.101.0.0/16); шаблоны nginx-конфигов обращаются к нему по имени flibusta-fpm, так что фиксированный адрес нужен скорее для предсказуемости, чем для работы. Подсеть при создании сети должна включать этот адрес.

Если используется Redis, он должен быть доступен по любой из этих сетей — проще всего подключить его к flibusta_net. В шаблоне есть закомментированная сеть redis_net на случай, если Redis живёт отдельно.

Минимальный рабочий набор

Если отбросить всё необязательное, для запуска достаточно:

environment:
  - TZ=Europe/Moscow
  - FLIBUSTA_DBHOST=postgres
  - FLIBUSTA_DBPASSWORD_FILE=/run/secrets/FLIBUSTA_PWD
  - POSTGRES_ADMIN_DBPASSWORD_FILE=/run/secrets/POSTGRES_ADMIN_PWD
  - FLIBUSTA_APP_ADMIN=flibustadmin
  - FLIBUSTA_APP_ADMIN_PASSWORD_FILE=/run/secrets/FLIBUSTA_APP_ADMIN_PWD

Остальное возьмёт значения по умолчанию. Но FLIBUSTA_TRUSTED_NET, FLIBUSTA_WEBROOT и FLIBUSTA_ENABLE_MISSING_BOOK_DOWNLOAD стоит задать явно — именно от них зависит, кто и как попадает в библиотеку и будет ли она ходить в интернет. FLIBUSTA_REDIS_HOST в минимальный набор не входит намеренно: библиотека полностью работоспособна без Redis, и добавить его можно в любой момент позже.