BookStack: мой опыт настройки и использования open-source базы знаний

Почему я выбрал именно BookStack

Мы в команде давно искали удобный инструмент для хранения технической документации и инструкций. Пробовали всё подряд — от Wiki.js до Confluence. Но то санкции, то интерфейс перегружен, то кастомизация страдает. В какой-то момент я наткнулся на BookStack — лёгкую, симпатичную open-source платформу на Laravel. Решил попробовать. В итоге — развернул, настроил, и теперь она у нас в проде.

Расскажу, как это было.

Установка BookStack на Ubuntu 24.04 (через официальный скрипт)

Самый простой и быстрый способ развернуть BookStack — воспользоваться официальным bash-скриптом, который автоматизирует установку всех зависимостей и конфигурацию. Я проверил это на чистой Ubuntu 24.04 — всё заработало без проблем.

1. Подготовка системы

Перед началом убедитесь, что у вас:

• Ubuntu 24.04 (минимальная версия)

• Права root или sudo

• Интернет-доступ для скачивания скрипта

Обновим пакеты:

sudo apt update && sudo apt upgrade -y

Скрипт установки Ubuntu 24.04:

# Скачать скрипт wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh  # Сделать его исполняемым chmod a+x installation-ubuntu-24.04.sh  # Запустить скрипт с правами администратора sudo ./installation-ubuntu-24.04.sh

Что делает скрипт:
Ссылка на скрипт

#!/bin/bash  echo "This script installs a new BookStack instance on a fresh Ubuntu 24.04 server." echo "This script does not ensure system security." echo ""  # Создание пути для файла лога для отладки LOGPATH=$(realpath "bookstack_install_$(date +%s).log")  # Получение текущего пользователя, запускающего скрипт SCRIPT_USER="${SUDO_USER:-$USER}"  # Получение IP-адреса текущей машины CURRENT_IP=$(ip addr | grep 'state UP' -A4 | grep 'inet ' | awk '{print $2}' | cut -f1  -d'/')  # Генерация пароля для базы данных DB_PASS="$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 13)"  # Каталог для установки BookStack BOOKSTACK_DIR="/var/www/bookstack"  # Получение домена из аргументов (запрашивается позже, если не указано) DOMAIN=$1  # Предотвращение интерактивных запросов в приложениях export DEBIAN_FRONTEND=noninteractive  # Вывод сообщения об ошибке в командную строку и завершение программы # Также записывает сообщение в файл лога function error_out() {   echo "ERROR: $1" | tee -a "$LOGPATH" 1>&2   exit 1 }  # Вывод информационного сообщения в командную строку и файл лога function info_msg() {   echo "$1" | tee -a "$LOGPATH" }  # Выполнение проверок перед установкой, чтобы избежать нарушения существующей настройки веб-сервера function run_pre_install_checks() {   # Проверка, запущен ли скрипт от имени root, и завершение, если нет   if [[ $EUID -gt 0 ]]   then     error_out "This script must be ran with root/sudo privileges"   fi    # Проверка, установлен ли Apache, и завершение, если он уже установлен   if [ -d "/etc/apache2/sites-enabled" ]   then     error_out "This script is intended for a fresh server install, existing apache config found, aborting install"   fi    # Проверка, установлена ли MySQL, и завершение, если данные MySQL уже существуют   if [ -d "/var/lib/mysql" ]   then     error_out "This script is intended for a fresh server install, existing MySQL data found, aborting install"   fi }  # Получение домена из первого переданного параметра или запрос ввода домена у пользователя function run_prompt_for_domain_if_required() {   if [ -z "$DOMAIN" ]   then     info_msg ""     info_msg "Enter the domain (or IP if not using a domain) you want to host BookStack on and press [ENTER]."     info_msg "Examples: my-site.com or docs.my-site.com or ${CURRENT_IP}"     read -r DOMAIN   fi    # Завершение с ошибкой, если домен не указан   if [ -z "$DOMAIN" ]   then     error_out "A domain must be provided to run this script"   fi }  # Установка основных системных пакетов function run_package_installs() {   apt update   apt install -y git unzip apache2 curl mysql-server-8.0 php8.3 \   php8.3-fpm php8.3-curl php8.3-mbstring php8.3-ldap php8.3-xml php8.3-zip php8.3-gd php8.3-mysql }  # Настройка базы данных function run_database_setup() {   # Убедиться, что служба базы данных запущена   systemctl start mysql-server.service   sleep 3    # Создание необходимой базы данных, пользователя и прав доступа   mysql -u root --execute="CREATE DATABASE bookstack;"   mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED WITH mysql_native_password BY '$DB_PASS';"   mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;" }  # Загрузка BookStack function run_bookstack_download() {   cd /var/www || exit   git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack }  # Установка Composer function run_install_composer() {   EXPECTED_CHECKSUM="$(php -r 'copy("https://composer.github.io/installer.sig", "php://stdout");')"   php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"   ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"    if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]   then       >&2 echo 'ERROR: Invalid composer installer checksum'       rm composer-setup.php       exit 1   fi    php composer-setup.php --quiet   rm composer-setup.php    # Перемещение Composer в глобальную установку   mv composer.phar /usr/local/bin/composer }  # Установка зависимостей BookStack через Composer function run_install_bookstack_composer_deps() {   cd "$BOOKSTACK_DIR" || exit   export COMPOSER_ALLOW_SUPERUSER=1   php /usr/local/bin/composer install --no-dev --no-plugins }  # Копирование и обновление переменных окружения BookStack function run_update_bookstack_env() {   cd "$BOOKSTACK_DIR" || exit   cp .env.example .env   sed -i.bak "s@APP_URL=.*\$@APP_URL=http://$DOMAIN@" .env   sed -i.bak 's/DB_DATABASE=.*$/DB_DATABASE=bookstack/' .env   sed -i.bak 's/DB_USERNAME=.*$/DB_USERNAME=bookstack/' .env   sed -i.bak "s/DB_PASSWORD=.*\$/DB_PASSWORD=$DB_PASS/" .env   # Генерация ключа приложения   php artisan key:generate --no-interaction --force }  # Выполнение первоначальных миграций базы данных BookStack function run_bookstack_database_migrations() {   cd "$BOOKSTACK_DIR" || exit   php artisan migrate --no-interaction --force }  # Установка прав доступа к файлам и папкам # Устанавливает текущего пользователя как владельца и группу www-data как владельца группы, # затем предоставляет группе права на запись только для необходимых каталогов. # Скрывает файл `.env`, чтобы он не был виден другим пользователям в системе. function run_set_application_file_permissions() {   cd "$BOOKSTACK_DIR" || exit   chown -R "$SCRIPT_USER":www-data ./   chmod -R 755 ./   chmod -R 775 bootstrap/cache public/uploads storage   chmod 740 .env    # Указание git игнорировать изменения прав доступа   git config core.fileMode false }  # Настройка Apache с необходимыми модулями и конфигурацией function run_configure_apache() {   # Включение необходимых модулей и конфигурации Apache   a2enmod rewrite proxy_fcgi setenvif   a2enconf php8.3-fpm    # Настройка необходимой конфигурации Apache для BookStack   cat >/etc/apache2/sites-available/bookstack.conf <<EOL <VirtualHost *:80>   ServerName ${DOMAIN}    ServerAdmin webmaster@localhost   DocumentRoot /var/www/bookstack/public/    <Directory /var/www/bookstack/public/>       Options -Indexes +FollowSymLinks       AllowOverride None       Require all granted       <IfModule mod_rewrite.c>           <IfModule mod_negotiation.c>               Options -MultiViews -Indexes           </IfModule>            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]       </IfModule>   </Directory>    ErrorLog \${APACHE_LOG_DIR}/error.log   CustomLog \${APACHE_LOG_DIR}/access.log combined  </VirtualHost> EOL    # Отключение сайта Apache по умолчанию и включение BookStack   a2dissite 000-default.conf   a2ensite bookstack.conf    # Перезапуск Apache для загрузки новой конфигурации   systemctl restart apache2   # Убедиться, что служба php-fpm запущена   systemctl start php8.3-fpm.service }  info_msg "This script logs full output to $LOGPATH which may help upon issues." sleep 1  run_pre_install_checks run_prompt_for_domain_if_required info_msg "" info_msg "Installing using the domain or IP \"$DOMAIN\"" info_msg "" sleep 1  info_msg "[1/9] Installing required system packages... (This may take several minutes)" run_package_installs >> "$LOGPATH" 2>&1  info_msg "[2/9] Preparing MySQL database..." run_database_setup >> "$LOGPATH" 2>&1  info_msg "[3/9] Downloading BookStack to ${BOOKSTACK_DIR}..." run_bookstack_download >> "$LOGPATH" 2>&1  info_msg "[4/9] Installing Composer (PHP dependency manager)..." run_install_composer >> "$LOGPATH" 2>&1  info_msg "[5/9] Installing PHP dependencies using composer..." run_install_bookstack_composer_deps >> "$LOGPATH" 2>&1  info_msg "[6/9] Creating and populating BookStack .env file..." run_update_bookstack_env >> "$LOGPATH" 2>&1  info_msg "[7/9] Running initial BookStack database migrations..." run_bookstack_database_migrations >> "$LOGPATH" 2>&1  info_msg "[8/9] Setting BookStack file & folder permissions..." run_set_application_file_permissions >> "$LOGPATH" 2>&1  info_msg "[9/9] Configuring apache server..." run_configure_apache >> "$LOGPATH" 2>&1  info_msg "----------------------------------------------------------------" info_msg "Setup finished, your BookStack instance should now be installed!" info_msg "- Default login email: admin@admin.com" info_msg "- Default login password: password" info_msg "- Access URL: http://$CURRENT_IP/ or http://$DOMAIN/" info_msg "- BookStack install path: $BOOKSTACK_DIR" info_msg "- Install script log: $LOGPATH" info_msg "---------------------------------------------------------------"

Завершение установки

После установки BookStack будет доступен по IP-адресу сервера (или домену, если настроен). По умолчанию:

• Логин: admin@admin.com

• Пароль: password (его надо сменить сразу же!)

Если хотите поменять URL, заголовки, язык, загрузки и прочее — всё настраивается в .env файле по пути /var/www/bookstack/.env.

Пример:

APP_URL=http://10.50.10.188 APP_LANG=ru FILE_UPLOAD_SIZE_LIMIT=50

После изменений не забудьте:

php artisan config:clear php artisan cache:clear

Как устроена структура в BookStack и почему она удобная

Всё построено по принципу «как в реальных книгах». Есть Полки, Книги, Главы и Страницы. Мне это сразу зашло — легко объяснить коллегам, где что лежит.

У нас, например:

• Полка DevOps

  • Книга CI/CD

    • Глава GitLab

      • Страница Автоматический деплой

Работает быстро, искать удобно, есть даже ссылки на конкретные абзацы.

Почему редакторы — это кайф

Два режима:

• Для коллег, которые не любят разметку — WYSIWYG.

• Для меня — Markdown. Поддержка подсветки кода, live preview, вставка сниппетов — очень удобно.

Безопасность, права доступа и интеграции

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

Аутентификацию подключили через GitHub — настроить легко, в официальной документации всё есть.

Что ещё круто

• Есть REST API — можно автоматизировать создание страниц

• Есть dark mode — коллеги кайфуют 🙂

• Работает шустро даже на слабом VPS

Вывод

Если вы ищете простую, удобную и красивую базу знаний — попробуйте BookStack. Установка занимает 10 минут, а пользы — море. У нас это стал must-have инструмент в инфраструктуре.