Как установить и настроить BookStack на VPS

MAATRIX

Документация команды растёт быстрее, чем успевает укладываться в голове: инструкции разбросаны по чатам, гайды — в закреплённых сообщениях, а Confluence или Notion тянут за собой подписку и данные на чужих серверах. BookStack решает это просто — понятная иерархия «книга → глава → страница», WYSIWYG-редактор без магии Markdown-синтаксиса и вся база знаний на вашем VPS под полным контролем. Ниже — установка с нуля: PHP, MariaDB, веб-сервер, SSL и первичная настройка, чтобы через час у вас была рабочая база знаний, а не список открытых вкладок с документацией.

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

BookStack — PHP-приложение на фреймворке Laravel, поэтому по требованиям он ближе к типичной CMS, чем к тяжёлым Docker-стекам. Для команды до 30-50 человек с обычным объёмом текста и картинок хватает скромного VPS.

Дополнительно понадобится:

• домен или поддомен, направленный A-записью на IP сервера (без домена SSL не выпустить, а работать по голому IP для базы знаний неудобно и небезопасно);
• доступ по SSH с правами sudo;
• 10-15 минут на установку зависимостей.

В этом гайде ставим BookStack классическим способом — PHP + MariaDB + Nginx напрямую на сервере, без Docker. Так проще диагностировать проблемы и обновлять систему поэтапно; если предпочитаете контейнеры, у BookStack есть официальный docker-compose, но логика настройки .env и базы данных остаётся той же.

Подготовка сервера: PHP, MariaDB, зависимости

Обновите систему и поставьте базовые пакеты:

apt update && apt -y upgrade
apt -y install curl unzip git software-properties-common

BookStack требует PHP 8.1 или новее. В репозиториях Ubuntu 24.04 идёт PHP 8.3, чего вполне достаточно:

apt -y install php php-fpm php-mysql php-mbstring php-xml php-gd php-curl php-zip php-bcmath php-tokenizer php-intl
php -v

Убедитесь, что версия 8.1+. Если на сервере более старая ОС и в стандартных репозиториях только PHP 7.x, добавьте PPA Ondřej Surý (для Ubuntu):

add-apt-repository ppa:ondrej/php
apt update
apt -y install php8.3 php8.3-fpm php8.3-mysql php8.3-mbstring php8.3-xml php8.3-gd php8.3-curl php8.3-zip php8.3-bcmath php8.3-tokenizer php8.3-intl

Теперь MariaDB — она немного легче MySQL и полностью совместима с BookStack:

apt -y install mariadb-server
mysql_secure_installation

На вопросы secure_installation отвечайте: задать root-пароль — да, удалить анонимных пользователей — да, запретить удалённый вход root — да, удалить тестовую базу — да, обновить привилегии — да. Дальше создайте базу и пользователя под BookStack:

mysql -u root -p

CREATE DATABASE bookstack;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'ЗАМЕНИТЕ_НА_СЛОЖНЫЙ_ПАРОЛЬ';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Пароль сгенерируйте случайный (например, openssl rand -base64 24) и сохраните — он понадобится в .env на следующем шаге.

Установка BookStack и настройка .env

BookStack ставится через Composer — менеджер зависимостей PHP. Если его нет:

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

Клонируйте стабильную ветку BookStack в каталог сайта:

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

Composer подтянет зависимости Laravel — на слабом канале это может занять пару минут. Теперь настройте окружение:

cp .env.example .env

Откройте .env и пропишите доступ к базе и адрес сайта:

APP_URL=https://knowledge.example.com
APP_KEY=

DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=ЗАМЕНИТЕ_НА_СЛОЖНЫЙ_ПАРОЛЬ

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

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

Права на каталоги — BookStack пишет загрузки, кэш и логи, поэтому веб-сервер должен иметь доступ на запись:

chown -R www-data:www-data /var/www/bookstack
find /var/www/bookstack -type f -exec chmod 644 {} \;
find /var/www/bookstack -type d -exec chmod 755 {} \;
chmod -R 775 /var/www/bookstack/public/uploads /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache

Nginx и SSL-сертификат

Ставим Nginx, если его ещё нет:

apt -y install nginx

Создайте конфиг /etc/nginx/sites-available/bookstack:

server {
    listen 80;
    server_name knowledge.example.com;
    root /var/www/bookstack/public;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }

    client_max_body_size 20M;
}

Значение fastcgi_pass должно совпадать с версией PHP-FPM, которую вы поставили (проверить сокет — ls /run/php/). client_max_body_size увеличен, чтобы в базу знаний можно было загружать скриншоты и вложения крупнее дефолтного 1 МБ.

Активируйте сайт и перезапустите Nginx:

ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Теперь SSL через Let's Encrypt. Ставить его вручную дольше и муторнее, чем через certbot с готовым плагином для Nginx — он сам пропишет редирект и продлит сертификат по крону:

apt -y install certbot python3-certbot-nginx
certbot --nginx -d knowledge.example.com

Certbot спросит почту для уведомлений об истечении и предложит принудительный редирект с http на https — соглашайтесь. Если нужна более гибкая связка (несколько сайтов на одном сервере или Cloudflare перед VPS), почитайте про настройку Nginx как реверс-прокси — тот же принцип применим и к BookStack за прокси.

Первый вход и настройка структуры базы знаний

Откройте https://knowledge.example.com — должна появиться страница входа. Стандартные учётные данные для первого захода:

• Email: admin@admin.com
• Пароль: password

Сразу после входа зайдите в профиль и смените и почту, и пароль — дефолтные значения знает любой, кто хоть раз ставил BookStack, и оставлять их даже на пару часов не стоит.

Дальше — структура. BookStack строится вокруг трёх уровней:

• Книга (Book) — верхнеуровневая тема, например «Инфраструктура» или «Онбординг».
• Глава (Chapter) — необязательный промежуточный уровень внутри книги, группирует страницы по подтеме.
• Страница (Page) — сам контент, редактируется в WYSIWYG или, по желанию, в Markdown-режиме (переключается в настройках профиля).

Права доступа настраиваются на нескольких уровнях: ролями (Settings → Roles) и точечно — на конкретную книгу, главу или страницу через вкладку Permissions. Это удобно, когда часть базы должна быть открыта всей команде, а часть — только отделу или конкретным людям. Роль по умолчанию Editor даёт создавать и редактировать контент, Viewer — только читать; для админов остаётся системная роль Admin.

Если в компании уже есть каталог пользователей, BookStack умеет входить через LDAP или SAML2/OIDC — настраивается в .env (переменные AUTH_METHOD, LDAP_SERVER и связанные) без дополнительных пакетов, но это отдельная тема, которая выходит за рамки базовой установки.

Бэкапы, обновление и типичные проблемы

BookStack хранит данные в двух местах: база MariaDB (весь текст, структура, права) и каталог storage/uploads и public/uploads (загруженные файлы и изображения). Бэкапить нужно оба.

Дамп базы:

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

Архив загрузок:

tar -czf bookstack_uploads_$(date +%F).tar.gz -C /var/www/bookstack public/uploads storage/uploads

Оба шага стоит вынести в cron и складывать копии за пределы сервера — на объектное хранилище или другой VPS. Если база знаний растёт и бэкапы делаются вручную от случая к случаю, посмотрите на автоматизацию бэкапов с шифрованием — тот же подход подходит и для пары «MariaDB + каталог uploads».

Обновление до новой версии:

cd /var/www/bookstack
git fetch --all --tags
git checkout release
git pull
composer install --no-dev --optimize-autoloader
php artisan migrate --no-interaction --force
php artisan view:clear
chown -R www-data:www-data /var/www/bookstack

Перед обновлением всегда делайте свежий дамп базы — миграции необратимы, а откатываться без бэкапа придётся вручную по SQL.

Из частых проблем на практике:

• Белый экран или 500 ошибка после установки. Обычно не хватает прав на storage/ и bootstrap/cache — перепроверьте команды chmod выше, а подробности смотрите в storage/logs/laravel.log.
• Не загружаются изображения. Проверьте client_max_body_size в Nginx и upload_max_filesize/post_max_size в php.ini (/etc/php/8.3/fpm/php.ini) — оба лимита должны совпадать с реальным размером файлов.
• Письма не отправляются (приглашения, сброс пароля). BookStack сам не работает как почтовый сервер — нужен внешний SMTP, настройки в .env (MAIL_HOST, MAIL_PORT, MAIL_USERNAME). Если своего SMTP нет, проще всего подключить стороннего провайдера рассылок, чем поднимать почтовый сервер ради нескольких системных писем.

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