Пошаговая инструкция · Самостоятельная установка
Как установить BookStack на сервер
Пошаговая инструкция для самостоятельной установки. Установим BookStack на Ubuntu 26.04 небольшими шагами: объясним команды, включим HTTPS, настроим почту и проверим первую книгу и резервную копию.
Что подготовить перед установкой #
Установим BookStack — базу знаний с книгами, главами и страницами. Используем официальный ручной способ: Nginx выдаёт сайт, PHP-FPM выполняет приложение, MySQL хранит записи. Команды рассчитаны на чистую Ubuntu 26.04. Подготовьте сервер, домен и SSH-пользователя с sudo; не запускайте поверх существующих сайтов.
Понадобятся Ubuntu Server 26.04 LTS, пользователь с правом sudo, домен и почтовый адрес администратора. Размер сервера выберите по руководству BookStack. Сначала пройдите подготовку Ubuntu, включая доступ по SSH — защищённое подключение к командной строке сервера. В общей подготовке установите также Nginx и Certbot; Docker для этой ручной установки не нужен.
Все команды ниже выполняйте в SSH-терминале сервера, если явно не написано иначе. Домен kb.example.org заменяйте своим в каждой команде и файле. Пароли и ключи храните в менеджере паролей; значения из примеров не подходят для рабочей установки.
Официальный автоматический установщик использует Apache. Для этой схемы его не запускаем: шаги ниже следуют ручной установке BookStack, а HTTPS настраивается через Certbot для Nginx.
Дополнительные официальные источники: Релиз v26.09.1, Настройка почты, Резервное копирование и восстановление, Обновление, Права на файлы.
Шаг 1. Направьте домен на сервер #
В панели управления доменом создайте A-запись для kb.example.org с публичным IPv4 сервера. Это связывает имя с адресом машины. Не добавляйте AAAA, если IPv6 не настроен. После сохранения проверьте имя на сервере.
getent ahostsv4 kb.example.orgВ выводе должен быть публичный IPv4 вашего сервера. Если адрес другой или вывода нет, исправьте DNS и дождитесь обновления записи. Сертификат пока не выпускайте.
Шаг 2. Установите веб-сервер, PHP и базу #
Добавим Nginx, PHP 8.5-FPM с расширениями BookStack и MySQL. Composer устанавливает PHP-зависимости приложения. Это компоненты одной установки; BookStack ещё не скачан. Если ошибка указывает на отсутствующий пакет, исправьте её до следующего шага.
sudo apt update
sudo apt install -y nginx mysql-server git curl unzip nano composer \
php8.5-fpm php8.5-cli php8.5-curl php8.5-mbstring php8.5-ldap \
php8.5-xml php8.5-zip php8.5-gd php8.5-mysqlapt завершился без ошибок. php -v показывает 8.5, composer --version — 2.x. Расширения должны относиться к той же ветке PHP.
Шаг 3. Разрешите SSH и доступ к сайту #
Откроем порты 80 и 443 для HTTP и HTTPS. Сначала разрешаем OpenSSH, чтобы не потерять подключение при включении firewall. Если у провайдера есть отдельный сетевой firewall, разрешите там те же порты. Порт базы данных 3306 снаружи не нужен.
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw statusПодтвердите включение клавишей y. В статусе должны быть разрешены OpenSSH, 80/tcp и 443/tcp. Оставьте текущий SSH-сеанс открытым и проверьте вход во втором окне терминала.
Шаг 4. Подготовьте пароль базы #
Получите случайный пароль. Сохраните его в менеджере паролей: он будет нужен MySQL и DB_PASSWORD в .env. Он отличается от будущего пароля администратора BookStack.
openssl rand -hex 32Сохранено 64 шестнадцатеричных символа; не используйте значение из чужого примера.
Шаг 5. Создайте базу и отдельного пользователя #
Во всём блоке замените REPLACE_DB_PASSWORD сохранённым значением. MySQL-пользователь bookstack получает права только на свою базу; приложение не подключается под root. Копируйте блок целиком, включая завершающую строку SQL.
sudo mysql <<'SQL'
CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'REPLACE_DB_PASSWORD';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
SQLКоманда завершилась без ERROR. Если база или пользователь уже существуют, разберите прежнюю установку; не удаляйте их ради повторного запуска.
Шаг 6. Скачайте BookStack v26.09.1 #
Получим код конкретного релиза. Каталог принадлежит вашему SSH-пользователю, группа www-data потребуется PHP. На сервере до этого шага не должно быть установленной BookStack в том же каталоге.
sudo install -d -o "$USER" -g www-data -m 750 /var/www/bookstack
git clone https://source.bookstackapp.com/bookstack.git --branch v26.09.1 --single-branch /var/www/bookstack
cd /var/www/bookstackВы в /var/www/bookstack. git describe --tags --exact-match выводит v26.09.1.
Шаг 7. Установите зависимости приложения #
Выполняйте Composer от своего обычного пользователя, из каталога BookStack. Он читает зафиксированные зависимости релиза; --no-dev исключает инструменты разработки. Нельзя скрывать ошибки PHP параметром --ignore-platform-reqs.
cd /var/www/bookstack
composer install --no-dev --prefer-distУстановка закончилась успешно и появился vendor. Ошибка расширения PHP требует установить нужное расширение, затем повторить этот шаг.
Шаг 8. Заполните .env #
Сначала выполните cp .env.example .env, затем nano .env в /var/www/bookstack. Измените перечисленные строки, сохранив остальные. Домен и пароль замените своими. APP_URL сразу использует HTTPS: публичный вход настроим после подготовки базы.
/var/www/bookstack/.envAPP_URL=https://kb.example.org
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=REPLACE_DB_PASSWORDСохраните Ctrl+O, Enter, Ctrl+X. DB_PASSWORD совпадает с паролем роли MySQL; APP_KEY пока оставьте как в образце.
Шаг 9. Создайте ключ приложения #
APP_KEY защищает зашифрованные данные. Генерируем его один раз для новой установки; при переносе или восстановлении сохраняем прежний ключ.
php artisan key:generateКоманда сообщила об установленном application key. .env теперь содержит APP_KEY; не запускайте генерацию повторно после появления рабочих данных.
Шаг 10. Подготовьте таблицы BookStack #
Миграция создаёт таблицы приложения в уже подготовленной базе. --force разрешает действие для рабочей конфигурации; это не команда восстановления чужой базы.
php artisan migrate --forceМиграции завершились без ошибки подключения. При отказе MySQL сверяйте DB_HOST, DB_USERNAME и пароль из .env.
Шаг 11. Создайте владельца до публикации сайта #
В той же SSH-сессии зададим почту и пароль первого администратора. read -s скрывает ввод пароля. Команда --initial обновляет исходную административную запись: стандартный пароль password нельзя оставлять. Замените адрес своей почтой.
read -r -s -p "Пароль администратора BookStack: " BOOKSTACK_ADMIN_PASSWORD
printf "\n"
php artisan bookstack:create-admin --initial --email="admin@example.org" --name="Admin" --password="$BOOKSTACK_ADMIN_PASSWORD"
unset BOOKSTACK_ADMIN_PASSWORDКоманда сообщила об административном пользователе. Сохраните выбранный пароль; это пароль входа, а не DB_PASSWORD.
Шаг 12. Разрешите PHP читать приложение и сохранять файлы #
Код принадлежит вашему пользователю; PHP читает его через группу www-data. Письмо в каталоги storage, cache и uploads нужно для журналов, кеша и вложений. .env доступен только владельцу и группе. Права 777 здесь не нужны.
sudo chown -R "$USER":www-data /var/www/bookstack
chmod -R 750 /var/www/bookstack
chmod -R 770 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
chmod 640 /var/www/bookstack/.envПрава применены без ошибок. PHP-FPM использует www-data; при ошибке 500 проверьте права нужного каталога и журнал, не открывайте запись ко всему коду.
Шаг 13. Сохраните сайт Nginx #
Откройте sudo nano /etc/nginx/sites-available/bookstack, вставьте файл и замените kb.example.org своим доменом. Корень сайта — только public: .env и служебные файлы не должны выдаваться браузеру. try_files направляет страницы в index.php, PHP-FPM выполняет этот файл через локальный сокет. До HTTPS обычные HTTP-запросы блокируются ответом 403.
/etc/nginx/sites-available/bookstackserver {
listen 80;
server_name kb.example.org;
root /var/www/bookstack/public;
index index.php;
client_max_body_size 100m;
location / {
if ($scheme = http) { return 403; }
try_files $uri $uri/ /index.php?$query_string;
}
location = /index.php {
if ($scheme = http) { return 403; }
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param HTTPS $https if_not_empty;
fastcgi_pass unix:/run/php/php8.5-fpm.sock;
}
location ~ \.php$ { return 404; }
location ~ /\.(?!well-known).* { deny all; }
}Сохраните Ctrl+O, Enter, Ctrl+X. В файле пока нет путей к сертификатам: Nginx сможет проверить его до выпуска HTTPS.
Шаг 14. Подключите сайт и проверьте HTTP #
Ссылка подключает сохранённый сайт. nginx -t проверяет все настройки сервера; && разрешает перечитать их только при успешной проверке. curl проверяет ответ для вашего домена. При ошибке остановитесь, исправьте указанную строку и повторите проверку.
sudo ln -sfn /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/bookstack
sudo nginx -t && sudo systemctl reload nginx
curl -I http://kb.example.org/Ожидается successful от nginx -t и HTTP 403 для обычного запроса: до HTTPS это намеренная блокировка. DNS должен указывать на сервер, TCP 80/443 — быть доступен у провайдера. Ничего не вводите в форму входа по HTTP.
Шаг 15. Получите сертификат и включите HTTPS #
Каждое имя из команды должно указывать на этот сервер. Certbot проверит домены, сам добавит сертификат в сайт Nginx и включит перенаправление HTTP → HTTPS. Укажите свою почту при запросе и подтвердите условия Let’s Encrypt. Это отдельное действие после успешной проверки HTTP.
sudo /snap/bin/certbot --nginx -d kb.example.org --redirectCertbot сообщил об успешной установке. Откройте HTTPS-адрес со своего компьютера: браузер не должен предупреждать о сертификате. Для закрытой панели используйте разрешённый IP. При ошибке исправьте DNS, в том числе AAAA, либо доступ к TCP 80; не повторяйте запросы выпуска подряд.
Шаг 16. Проверьте продление сертификата #
Certbot из snap создаёт службу автоматического продления. Dry-run выполняет пробное продление: настоящие сертификаты не заменяются. Затем проверьте, что таймер планирует следующий запуск. Сохраняйте доступ к TCP 80 для следующих проверок домена.
sudo /snap/bin/certbot renew --dry-run
systemctl list-timers --all 'snap.certbot.renew*'Пробное продление успешно, у таймера есть следующий запуск. Если тест не прошёл, проверьте /var/log/letsencrypt/letsencrypt.log; сначала исправьте причину. После этого можно создавать учётную запись и приглашать пользователей.
Шаг 17. Войдите как администратор #
В браузере откройте свой HTTPS-адрес. Войдите с почтой и паролем, заданными командой создания администратора. В настройках учётной записи включите второй фактор, если используете его, и сохраните данные восстановления. Для повседневной работы создайте обычного пользователя.
Выйдите и войдите заново с новым паролем. Убедитесь, что можете повторить вход и сохранили данные восстановления второго фактора.
Шаг 18. Заполните настройки отправки почты #
Почта нужна для приглашений и восстановления пароля. Получите у почтового провайдера SMTP-сервер, порт, логин и пароль. SMTP — протокол отправки писем. Адрес отправителя должен быть разрешён этим провайдером.
Откройте nano /var/www/bookstack/.env и измените существующие MAIL_* строки. Пример ниже подходит для SMTP с TLS на порту 587; если провайдер требует другой режим, используйте его параметры. Пароль помещайте в кавычки. Сохранение в nano: Ctrl+O, Enter, Ctrl+X.
MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.org
MAIL_PORT=587
MAIL_USERNAME=bookstack@example.org
MAIL_PASSWORD="ЗАМЕНИТЕ_ПАРОЛЕМ_SMTP"
MAIL_ENCRYPTION=tls
MAIL_FROM=bookstack@example.org
MAIL_FROM_NAME="База знаний"Все example.org и пароль должны быть заменены вашими значениями. Не добавляйте второй набор одинаковых MAIL_* строк.
Шаг 19. Отправьте пробное письмо #
После изменения .env ещё раз очистите кеш. Затем в браузере откройте настройки обслуживания BookStack и выполните отправку тестового письма на свою почту.
cd /var/www/bookstack
php artisan config:clearПисьмо должно прийти, включая проверку папки «Спам». Если его нет, проверьте SMTP-логин, разрешённый адрес отправителя и журнал BookStack. Не приглашайте сотрудников, пока доставка не заработала.
Шаг 20. Закройте базу знаний от посторонних #
Для внутренней базы в административных настройках отключите публичную регистрацию и публичный доступ. Создайте отдельного пользователя для повседневной работы и назначьте нужную роль. Роль определяет, какие книги человек может читать и редактировать.
Откройте адрес в приватном окне браузера без входа: внутренние материалы не должны быть видны. Войдите обычным пользователем и убедитесь, что он видит только разрешённые книги.
Шаг 21. Создайте первую книгу и проверьте вложения #
В браузере создайте тестовую книгу, внутри неё главу и страницу с несколькими предложениями. Загрузите картинку и небольшой PDF. Это проверяет не только открытие сайта, но и запись данных и файлов.
Найдите страницу через поиск, откройте картинку и скачайте PDF. Повторите проверку под обычным читателем. Если вложение не открывается, разберите права доступа и ошибку до переноса рабочих документов.
Шаг 22. Сохраните копию базы данных #
Резервная копия BookStack состоит из базы и файлов. Сначала создадим закрытую папку и дамп — текстовый файл с данными MySQL. На время копирования остановим PHP-FPM, чтобы сотрудники не меняли материалы. Предупредите их о коротком перерыве.
Все команды двух следующих шагов выполняйте в одном SSH-сеансе: переменная BOOKSTACK_BACKUP хранит путь созданной папки. Если любая команда после остановки PHP-FPM не удалась, обязательно выполните sudo systemctl start php8.5-fpm, чтобы вернуть сайт.
umask 077
BOOKSTACK_BACKUP="$HOME/bookstack-backup-$(date +%F-%H%M)"
mkdir -p "$BOOKSTACK_BACKUP"
sudo systemctl stop php8.5-fpm
sudo mysqldump --single-transaction bookstack > "$BOOKSTACK_BACKUP/database.sql"Дамп должен завершиться без ошибки. Если MySQL отказал в доступе или база не найдена, запустите PHP-FPM обратно и проверьте DB_DATABASE в .env. Пустой файл не считается копией.
Шаг 23. Сохраните вложения и верните сайт #
Добавим .env, вложения, темы и настройки Nginx с сертификатами. Архивы содержат секреты и закрытые ключи; храните их в закрытом внешнем хранилище. Затем вернём PHP-FPM и доступ к сайту.
sudo tar -czpf "$BOOKSTACK_BACKUP/files.tar.gz" -C /var/www/bookstack .env public/uploads storage/uploads themes
sudo tar -czf "$BOOKSTACK_BACKUP/nginx-tls.tar.gz" /etc/nginx/sites-available/bookstack /etc/letsencrypt
sudo systemctl start php8.5-fpm
sudo chown "$USER:$(id -gn)" "$BOOKSTACK_BACKUP"/*.tar.gz
chmod 600 "$BOOKSTACK_BACKUP"/*Оба архива созданы без ошибок; HTTPS-сайт снова открывается. При ошибке архива сначала верните PHP-FPM, затем разберите причину и повторите копию.
Шаг 24. Проверьте файлы копии и перенесите их с сервера #
Посмотрим размер дампа и содержимое архива. После проверки скачайте всю папку BOOKSTACK_BACKUP через SFTP-клиент на другой компьютер или в закрытое хранилище. SFTP использует тот же защищённый доступ, что SSH. Копия на единственном сервере не поможет при потере его диска.
ls -lh "$BOOKSTACK_BACKUP"
sudo tar -tzf "$BOOKSTACK_BACKUP/files.tar.gz" | head -n 20Дамп и архив должны иметь ненулевой размер; в архиве должны быть .env и каталоги uploads. Проверьте, что скачанная копия тоже открывается. Удаление или обновление приложения до этой проверки откладывайте.
Что делать при ошибках и перед обновлением #
Если сайт отвечает ошибкой 500, посмотрите последние строки /var/www/bookstack/storage/logs/laravel.log и /var/log/nginx/error.log. Команда sudo tail -n 50 ПУТЬ_К_ФАЙЛУ показывает конец журнала. Ошибки сертификата проверяют отдельно: sudo /snap/bin/certbot renew --dry-run должно завершиться успешно. Не публикуйте журналы вместе с паролями и ключами.
Копию нужно хотя бы один раз восстановить на отдельном тестовом сервере с той же версией BookStack. Верните базу и архив, сохраните прежний APP_KEY, адаптируйте адрес и реквизиты базы, затем проверьте вход, поиск, вложения и роли. Подробный порядок есть в официальном руководстве восстановления.
Перед обновлением прочитайте официальные инструкции, выберите конкретный релиз и создайте свежую полную копию. Для этой ручной установки зависимости обновляет Composer; испытайте новый релиз на восстановленной копии. Откат файлов после миграции базы не заменяет восстановление дампа.
На тестовом сервере восстановите Nginx и сертификаты либо получите сертификат для отдельного тестового домена. До перечитывания службы проверьте sudo nginx -t. Сокет PHP должен соответствовать установленной ветке 8.5.