BookStack на Ubuntu 24.04: пошаговая установка

MAATRIX

Confluence стоит дорого и требует лицензии, а обычная вики вроде MediaWiki перегружена разметкой, которую никто в команде не хочет учить. BookStack закрывает этот разрыв: простая иерархия «книга → глава → страница», привычный WYSIWYG-редактор (с опцией переключиться на Markdown) и никакого месячного счёта. Ниже — установка с нуля на Ubuntu 24.04: nginx, PHP 8.3, MariaDB, composer, права доступа и фоновые задачи по cron, с реальными командами и типичными местами, где всё ломается.

Что понадобится до установки

BookStack — обычное Laravel-приложение на PHP, без Docker и без Node.js на сервере: сборка фронтенда уже лежит в ветке release репозитория. Стек простой:

Подготовьте: чистую Ubuntu 24.04 LTS с root-доступом, от 1 vCPU / 1 ГБ RAM для небольшой команды (BookStack легче Nextcloud — файлов и превью почти нет), домен с A-записью на IP сервера и открытые порты 80/443. Проверьте домен командой dig +short wiki.example.com — должен совпасть с curl -s ifconfig.me.

Отдельно проверьте минимальную версию PHP: официальный composer.json проекта на GitHub жёстко её фиксирует, и на момент актуальных веток BookStack это PHP 8.1 или новее — в репозитории Ubuntu 24.04 сразу PHP 8.3, так что попадаете в требования автоматически. Если ставите очень свежий релиз через год-два после этой статьи, свериться с composer.json перед стартом не помешает — минимальная версия иногда поднимается.

Шаг 1. Устанавливаем nginx, MariaDB и PHP 8.3

Всё — из штатных репозиториев Ubuntu 24.04, без сторонних PPA:

apt update && apt -y full-upgrade
apt -y install nginx mariadb-server git unzip curl composer \
  php8.3-fpm php8.3-mysql php8.3-xml php8.3-mbstring php8.3-curl \
  php8.3-zip php8.3-gd php8.3-bcmath php8.3-intl

Пакет php8.3-common, который подтянется как зависимость php8.3-fpm, уже несёт ctype, tokenizer, fileinfo, openssl и pdo — отдельно их ставить не нужно, в отличие от mbstring, xml, curl, zip, gd, bcmath и intl. Проверка набора одной строкой:

php -m | grep -icE 'mbstring|xml|curl|zip|gd|bcmath|intl|pdo_mysql|tokenizer|ctype|fileinfo'

Должно вернуть 10. Не хватает pdo_mysql — значит забыли php8.3-mysql, и установка ниже упадёт на первой миграции с could not find driver. intl формально не обязателен, но без него сортировка заголовков по алфавиту в некоторых локалях едет по порядку байт, а не букв — для русского это заметно.

Фаервол сразу приводим в порядок — подробный разбор в статье про UFW на Ubuntu 24.04, а минимальный набор такой:

ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp
ufw --force enable

MariaDB наружу не открываем — ss -ltnp | grep 3306 должен показывать 127.0.0.1, а не 0.0.0.0.

Шаг 2. База данных для BookStack

MariaDB после установки уже запущена, но не защищена. Если ставите её на этот сервер впервые — сначала пройдите базовую защиту MariaDB на Ubuntu 24.04, а затем создайте базу и пользователя именно под BookStack:

mariadb -u root -e "
CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'ДЛИННЫЙ_ПАРОЛЬ';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;"

utf8mb4 — не формальность: с обычным utf8 (в MySQL-семье это урезанный трёхбайтовый вариант) эмодзи и часть иероглифов в заголовках страниц ломают вставку записи ошибкой Incorrect string value. Пользователя привязываем к localhost, а не к %: PHP-FPM и MariaDB стоят на одной машине, ходить в базу по TCP извне незачем, и это на пункт снижает поверхность атаки.

Шаг 3. Код BookStack и зависимости composer

Клонируем именно ветку release — в ней лежит уже собранный фронтенд (CSS и JS), и Node.js на сервере не понадобится:

cd /var/www
git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
cd bookstack
composer install --no-dev --optimize-autoloader

--no-dev пропускает пакеты для разработки (тесты, отладка) — на проде они не нужны и только увеличивают vendor/ без пользы. --optimize-autoloader строит классовую карту заранее, а не резолвит пространства имён на каждом запросе — на слабом VPS разница в отклике при первой загрузке страницы заметна на глаз. Клонирование и установка зависимостей занимают минуту-две, vendor/ весит около 150–200 МБ — точная цифра зависит от версии.

Частая ошибка на этом шаге — забыть --branch release и склонировать main: там лежат сырые непересобранные ассеты, и после установки страницы открываются без стилей, голым HTML. Если так вышло — не переустанавливайте всё заново, просто git checkout release в уже склонированном каталоге.

Шаг 4. .env, ключ приложения и миграции базы

Конфиг — обычный для Laravel .env-файл:

cp .env.example .env
nano .env

Минимум, что там нужно поменять:

APP_URL=https://wiki.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=ДЛИННЫЙ_ПАРОЛЬ

APP_URL — не косметика: BookStack подставляет его в ссылки на статику и в абсолютные URL страниц. Указали http:// вместо https://, а сертификат уже стоит — получите предупреждение о смешанном контенте и часть иконок или скриптов не подгрузится. Дальше — ключ приложения и миграции схемы:

php artisan key:generate --no-interaction --force
php artisan migrate --no-interaction --force

Без первой команды приложение при первом же открытии в браузере ответит No application encryption key has been specified — ключ шифрует сессии и часть служебных данных, без него BookStack просто откажется стартовать. Миграции создают все таблицы: книги, главы, страницы, роли, права доступа. Успешный прогон печатает список из полусотни с лишним файлов миграций с зелёным DONE напротив каждого; если оборвалось на середине с SQLSTATE[42000] — почти всегда это опечатка в имени базы или пароле в .env, а не проблема самого BookStack.

Шаг 5. Права доступа, nginx с TLS и cron

BookStack пишет на диск в трёх местах: storage/, bootstrap/cache/ и public/uploads/ (загруженные изображения и вложения). Отдаём их веб-серверу:

chown -R www-data:www-data /var/www/bookstack
chmod -R 755 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads

Забытый chown даёт при попытке загрузить обложку книги ошибку вида file_put_contents(): failed to open stream: Permission denied — она видна только в storage/logs/laravel.log, в браузере просто крутится спиннер.

Способ хранения файлов задаётся переменной STORAGE_TYPE в .env, и это стоит решить сразу:

Для одного VPS вариант local — разумный дефолт, менять его без реальной причины не нужно.

nginx-конфиг для Laravel-приложения короткий, специфика — в location для PHP и запрете доступа к служебным каталогам, /etc/nginx/sites-available/bookstack.conf:

server {
    listen 80;
    server_name wiki.example.com;
    root /var/www/bookstack/public;
    index index.php;

    client_max_body_size 50M;

    location / { try_files $uri $uri/ /index.php?$query_string; }
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
    location ~ /\.(?!well-known) { deny all; }
}

client_max_body_size поднят до 50 МБ — дефолтный 1 МБ nginx режет вложения (PDF, документы) раньше, чем они доходят до PHP, с ответом 413 Request Entity Too Large без единой строчки в логах BookStack — искать причину там бессмысленно, дело в nginx. root смотрит именно на public/, а не на корень репозитория — иначе .env с паролем от базы окажется доступен по прямой ссылке.

ln -s /etc/nginx/sites-available/bookstack.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
apt -y install certbot python3-certbot-nginx
certbot --nginx -d wiki.example.com --agree-tos -m admin@example.com --redirect

Certbot сам допишет блок на 443 и редирект с 80. Для автопродления сертификата и общего сравнения инструментов — Certbot или acme.sh для сервера.

Последний штрих — планировщик Laravel, на котором держится очистка корзины (удалённые страницы BookStack хранит в корзине ограниченное время) и часть служебных задач:

crontab -u www-data -e

и одна строка внутри:

* * * * * php /var/www/bookstack/artisan schedule:run >> /dev/null 2>&1

Без неё сама вики работает исправно, но корзина растёт бесконечно и часть отложенных уведомлений не уходит.

Какой сервер взять под BookStack

BookStack — лёгкое приложение: он не кодирует видео и не гоняет ML-модели, основная нагрузка — текстовые запросы к MariaDB и редкая отдача изображений.

• Минимум: 1 vCPU / 1–2 ГБ RAM / 20 ГБ NVMe — команде до 15–20 человек с обычным объёмом документации этого достаточно с запасом. PHP-FPM воркер съедает 30–50 МБ, MariaDB на маленькой базе укладывается в 150–250 МБ.
• С запасом: 2 vCPU / 4 ГБ RAM — если на том же сервере крутится ещё что-то (например, внутренняя база знаний с ИИ-поиском поверх той же вики) или команда за сотню человек с активной загрузкой вложений.
• Диск — сама база растёт медленно, основной расход места — вложения в public/uploads/. Для регулярного бэкапа удобен инструмент вроде BorgBackup на Ubuntu 24.04: дамп mysqldump bookstack плюс архив каталога uploads/ и файла .env.

Заказать VPS под BookStack можно в каталоге тарифов — российская локация снимает вопрос 152-ФЗ, если во внутренней вики окажутся персональные данные сотрудников, London и US-локации дают минимальный пинг зарубежным офисам. Оплата — картой российского банка, по СБП, криптовалютой или токеном MAAT, без иностранной карты для подписки не обойтись у Confluence, здесь этого барьера просто нет.

Частые вопросы