Почему я выбрал именно 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 инструмент в инфраструктуре.