Установка BookStack на Debian 12 — пошаговое руководство

Что такое BookStack

BookStack — свободное и открытое ПО для организации знаний в виде вики, написанное на PHP с использованием фреймворка Laravel. Подойдёт для внутренней документации, баз знаний и простого self-hosted портала для хранения информации.

Краткое определение терминов:

• LAMP: стек серверных компонентов — Linux, Apache, MariaDB/MySQL, PHP.
• Composer: менеджер зависимостей для PHP.
• .env: файл конфигурации приложения Laravel/BookStack.

Основные варианты использования

• Самостоятельная внутренняя вики для команды.
• Документация проектов и SOP.
• База знаний для поддержки клиентов.

Требования перед началом

• Сервер с Debian 12. Рекомендуется отдельный VPS или виртуальная машина.
• Ненулевой непользователь root с sudo-привилегиями.
• Домен, указывающий на IP сервера (для HTTPS).

Шаг 1 — Установка зависимостей

BookStack работает на PHP и использует MariaDB. На момент этого руководства поддерживается PHP 8.2. Установим Apache2, MariaDB, PHP, Composer и Git.

Обновите индекс пакетов:

sudo apt update

Установите требуемые пакеты:

sudo apt install apache2 mariadb-server composer curl php php-xml libapache2-mod-php php-fpm php-curl php-mbstring php-ldap php-tidy php-zip php-gd php-mysql git

Подтвердите установку, введя y, если потребуется. После установки проверьте состояние сервисов и версию PHP/Composer.

Проверка Apache:

sudo systemctl is-enabled apache2
sudo systemctl status apache2

Проверка MariaDB:

sudo systemctl is-enabled mariadb
sudo systemctl status mariadb

Проверка PHP и расширений:

php -v
php -m

На скриншоте показана версия PHP 8.2, которая совместима с BookStack.

Проверка Composer (пример вывода — Composer 2.5.5 установлен в /usr/bin/composer):

which composer
sudo -u www-data composer -v

Важно: версия Composer и PHP должна соответствовать требованиям BookStack; при обновлениях проекта проверяйте актуальные требования в репозитории.

Шаг 2 — Настройка PHP

Откройте файл конфигурации PHP для Apache: /etc/php/8.2/apache2/php.ini

sudo nano /etc/php/8.2/apache2/php.ini

Измените значения, адаптировав их под свою среду. Минимальные рекомендуемые правки:

date.timezone = Europe/Amsterdam
memory_limit = 512M

Примечание: установите date.timezone в ваш часовой пояс (например, Europe/Moscow для Москвы).

Сохраните файл и перезапустите Apache для применения изменений:

sudo systemctl restart apache2

Шаг 3 — Настройка MariaDB

Защитите установку MariaDB и создайте базу данных и пользователя для BookStack.

Запустите упрощённую утилиту безопасности:

sudo mariadb-secure-installation

Во время запуска утилиты:

• Нажмите Enter, если текущий root не имеет пароля.
• При предложении сменить метод аутентификации (unix_socket) введите n, если хотите оставить локальную привязку, или следуйте подсказкам. Обычно локальная unix_socket-аутентификация безопасна.
• Введите Y, чтобы задать пароль root MariaDB, и укажите сильный пароль.
• Отключите удалённую аутентификацию для root — рекомендуется Y.
• Удалите тестовую базу и анонимных пользователей — рекомендуется Y.
• Перезагрузите привилегии — Y.

Далее войдите в MariaDB как root:

sudo mariadb -u root -p

Создайте базу данных и пользователя для BookStack (замените имя базы и пароль на свои значения):

CREATE DATABASE bookstack;
CREATE USER bookstack@localhost IDENTIFIED BY 'p4ssword';
GRANT ALL ON bookstack.* TO bookstack@localhost WITH GRANT OPTION;
FLUSH PRIVILEGES;

Проверьте привилегии:

SHOW GRANTS FOR bookstack@localhost;

Выйдите из клиента MariaDB командой quit.

Безопасность базы:

• Используйте сильные уникальные пароли.
• По возможности ограничьте доступ к базе по локальному сокету или firewall.

Шаг 4 — Загрузка BookStack и установка зависимостей

Создайте каталоги конфигурации и кэша Composer и назначьте владельца www-data:

mkdir -p /var/www/{.config,.cache}
sudo chown -R www-data /var/www/{.config,.cache}

Клонируйте релизную ветку BookStack в /var/www/bookstack:

cd /var/www
git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack

Назначьте владельца каталога BookStack и перейдите в него:

sudo chown -R www-data:www-data /var/www/bookstack
cd /var/www/bookstack

Скопируйте .env.example в .env и отредактируйте параметры приложения:

sudo -u www-data cp .env.example .env
sudo -u www-data nano .env

Установите APP_URL на ваш домен и установите параметры подключения к БД:

# The application URL
APP_URL=http://bookstack.howtoforge.local

# Database values
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=p4ssword

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

Установите PHP-зависимости через Composer:

sudo -u www-data composer install --no-dev --no-plugins

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

sudo -u www-data php artisan key:generate --no-interaction --force
sudo -u www-data php artisan migrate --no-interaction --force

Назначьте корректные права на каталоги, которые должны быть доступны веб-серверу:

sudo chown www-data:www-data -R bootstrap/cache public/uploads storage
sudo chmod u+rw bootstrap/cache public/uploads storage

Защитите файл .env, чтобы только www-data и root имели доступ (например, 640):

sudo chmod -R 640 /var/www/bookstack/.env

Шаг 5 — Настройка виртуального хоста Apache

Включите модуль rewrite:

sudo a2enmod rewrite

Создайте конфигурацию виртуального хоста /etc/apache2/sites-available/bookstack.conf:

sudo nano /etc/apache2/sites-available/bookstack.conf

Вставьте конфигурацию, изменив ServerName на ваш домен (пример — bookstack.howtoforge.local):

    ServerName bookstack.howtoforge.local
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/bookstack/public/

    
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
        
            
                Options -MultiViews -Indexes
            
            RewriteEngine On
            # Handle Authorization Header
            RewriteCond %{HTTP:Authorization} .
            RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
            # Redirect Trailing Slashes If Not A Folder...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_URI} (.+)/$
            RewriteRule ^ %1 [L,R=301]
            # Handle Front Controller...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        
    

    ErrorLog ${APACHE_LOG_DIR}/bookstack-error.log
    CustomLog ${APACHE_LOG_DIR}/bookstack-access.log combined

Сохраните файл. Активируйте сайт и проверьте конфигурацию:

sudo a2ensite bookstack.conf
sudo apachectl configtest

Ожидаемый вывод: «Syntax OK». Затем перезапустите Apache:

sudo systemctl restart apache2

Шаг 6 — Защита HTTPS через Let’s Encrypt

Установите Certbot и плагин для Apache:

sudo apt install certbot python3-certbot-apache

Запустите Certbot для получения сертификата и автоматического внесения изменений в виртуальный хост Apache:

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email admin@example.com -d bookstack.howtoforge.local

Замените email и домен на ваши значения. После завершения сертификаты будут находиться в /etc/letsencrypt/live/<ваш_домен> и сайт будет автоматически перенаправлять HTTP→HTTPS.

Автоматическое обновление сертификатов: Certbot добавит cron/systemd таск. Для ручной проверки запускайте:

sudo certbot renew --dry-run

Шаг 7 — Доступ к BookStack

Откройте браузер и перейдите по адресу https://ваш_домен/.

Введите стандартные учётные данные (в примере):

• Email: [email protected]
• Пароль: password

После входа вы увидите панель управления BookStack.

Важно: при первом входе немедленно смените пароль администратора и настройте двухфакторную аутентификацию (если доступна) или интеграцию с внешней системой аутентификации (LDAP, SAML) при необходимости.

Пошаговая контрольная таблица (SOP) — кратко

• Установить пакеты LAMP, Composer, Git.
• Настроить php.ini (timezone, memory_limit).
• Запустить mariadb-secure-installation.
• Создать базу и пользователя MariaDB для BookStack.
• Клонировать BookStack, настроить .env.
• composer install, php artisan migrate.
• Настроить виртуальный хост Apache и модуль rewrite.
• Получить сертификат Let’s Encrypt.
• Войти в BookStack и сменить дефолтные пароли.

Приёмочные критерии (Критерии приёмки)

• Сайт доступен по HTTPS и корректно перенаправляет HTTP→HTTPS.
• Пользовательская регистрация/вход работают корректно.
• Таблицы базы данных успешно созданы и мигрированы.
• Папки storage, public/uploads, bootstrap/cache доступны для веб-сервера и защищены от записи неавторизованных пользователей.

Резервное копирование и восстановление

• Резервная копия базы: используйте mysqldump:

mysqldump -u root -p bookstack > bookstack-$(date +%F).sql

• Файлы приложения и загружаемые файлы: копируйте /var/www/bookstack и /var/www/bookstack/public/uploads.
• Восстановление: восстановите файлы и импортируйте дамп через mysql client.

Рекомендации: автоматизируйте бэкапы (cron), храните их вне сервера и проверяйте периодически целостность.

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

• Установите файлу .env права 640 и владельца www-data. Никогда не оставляйте .env доступным для чтения всеми.
• Настройте firewall (ufw/iptables) — откройте порты 80 и 443, закройте неиспользуемые.
• Ограничьте доступ к MariaDB по IP, если возможно.
• Регулярно обновляйте OS и зависимости PHP (composer update при необходимости в тестовой среде).
• Отключите Xdebug и другие dev-утилиты в продакшн.
• Мониторьте логи Apache, BookStack и MariaDB.

Советы по производительности

• Включите OPCache для PHP (уменьшает время ответа приложений на PHP).
• При большом числе пользователей используйте выделенный сервер БД или кластер.
• Для файлового хранилища рассмотрите использование NFS/S3-compatible хранилища.

Частые ошибки и как их решать

• Ошибка 500 после установки: проверьте логи Apache и storage/logs/laravel.log; проверьте права доступа на storage и bootstrap/cache.
• Ошибка подключения к БД: проверьте DB_* переменные в .env, убедитесь, что MariaDB слушает локально и пользователь создан.
• Сертификат не выпускается: убедитесь, что домен указывает на сервер и порт 80 открыт.

Когда этот метод не подойдёт (примеры)

• Требуется масштабируемая архитектура с множеством региональных реплик — монолитный BookStack на одном сервере не масштабируется автоматически.
• Нужны сложные интеграции SSO с корпоративными IdP, требующие отдельной поддержки и тестирования.
• Жёсткие требования к SLA и высокому трафику — стоит рассмотреть контейнеризацию и балансировку нагрузки.

Альтернативы и сравнение (кратко)

• MediaWiki: более функциональная, но сложнее в настройке.
• Wiki.js: современная Node.js альтернатива с поддержкой Markdown.
• Confluence: коммерческое решение с расширенной поддержкой и интеграциями.

Выбор зависит от требований по удобству, функциональности и поддержке.

Руководство ролей (Role-based checklist)

• Системный администратор:
  • Установить и обновлять ОС и пакеты.
  • Настроить firewall, SSL, бэкапы.
  • Назначить владельцев и права файлов.
• Администратор BookStack:
  • Настроить пользователей и роли в BookStack.
  • Управлять пространствами, шаблонами и правами доступа.
  • Проводить регулярные проверки безопасности и резервного копирования.
• Редактор/Автор:
  • Создавать и форматировать страницы/книги.
  • Следить за версионностью и ссылками.

Тест-кейсы и проверки (Критерии приёмки)

• Тест 1: Доступность — открыть https://ваш_домен и убедиться в загрузке главной страницы.
• Тест 2: Аутентификация — войти под админом и под обычным пользователем.
• Тест 3: Создание контента — создать книгу, главу и страницу.
• Тест 4: Загрузка файлов — загрузить файл в страницу и скачать его.
• Тест 5: Резервное восстановление — восстановить бэкап базы и проверить целостность контента.

Краткая методология развертывания (Mini-methodology)

1. Подготовьте инфраструктуру и домен.
2. Установите базовые компоненты (LAMP).
3. Настройте БД и пользователя.
4. Разверните приложение и выполните миграции.
5. Настройте HTTPS и права доступа.
6. Проведите тесты и введите в эксплуатацию.

Модель принятия решений (Decision tree)

flowchart TD
  A[Начало: есть сервер с Debian 12?] -->|Да| B[Есть домен?]
  B -->|Да| C[Установить LAMP и зависимости]
  B -->|Нет| D[Привязать домен к серверу]
  C --> E[Настроить PHP и MariaDB]
  E --> F[Клонировать BookStack и настроить .env]
  F --> G[composer install и migrate]
  G --> H[Настроить Apache vhost]
  H --> I[Выпустить SSL через Certbot]
  I --> J[Тесты и ввод в эксплуатацию]
  J --> K[Готово]
  D --> B

Советы по миграции и обновлению версии BookStack

• Всегда делайте полную резервную копию базы и файлов перед обновлением.
• Тестируйте обновление в окружении staging.
• Прочитайте примечания к релизу в GitHub, особенно по миграциям базы или требованиям PHP.

Приватность и соответствие (GDPR и заметки)

• BookStack может хранить личные данные в страницах. Решения:
  • Ограничить доступ к сервису из внутренних сетей.
  • Устанавливать политики хранения и удаления персональных данных.
  • Документировать, где и какие данные хранятся.
• Для соответствия GDPR организуйте процедуры удаления и экспорта данных по запросу.

Совместимость и заметки по версиям

• На момент руководства BookStack совместим с PHP 8.2.
• Composer версии 2.x требуется для установки зависимостей.
• При переходе на более новые версии PHP или BookStack проверьте release notes и тестируйте совместимость.

Шаблон контроля запуска (Runbook) — при ошибке 500

1. Проверить логи Apache: sudo tail -n 200 /var/log/apache2/bookstack-error.log
2. Проверить laravel лог: tail -n 200 /var/www/bookstack/storage/logs/laravel.log
3. Проверить права на storage и bootstrap/cache.
4. Проверить .env на корректность DB_* и APP_URL.
5. Откатить последние изменения и восстановить бэкап, если необходимо.

Часто задаваемые вопросы (коротко)

• Как сменить домен? Отредактируйте APP_URL в .env и обновите сертификат Let’s Encrypt.
• Как добавить LDAP? BookStack поддерживает LDAP через плагины/настройки — смотрите документацию проекта.
• Как увеличить доступную память PHP? Измените memory_limit в php.ini и перезапустите Apache.

Короткое объявление для команды (пример)

Установлен BookStack на https://bookstack.example.com. Пожалуйста, смените дефолтные пароли. Для вопросов по доступу обращайтесь к администратору.

Заключение

Вы успешно развернули BookStack на Debian 12. Дальше:

• Настройте пользователей и роли.
• Перенесите/создайте контент.
• Настройте регулярные бэкапы и мониторинг.

Важно: поддерживайте систему в актуальном состоянии и регулярно проверяйте безопасность. BookStack — удобный инструмент для организации знаний, но как и любое веб-приложение требует грамотного администрирования.

Краткий контрольный список перед вводом в эксплуатацию:

• HTTPS активно и автоматически обновляется.
• Резервное копирование настроено.
• Права на файлы и .env установлены.
• Администратор сменил пароль и включил доступы.