Как установить BookStack на Ubuntu 24.04

BookStack – система управления знаниями, предназначенная для создания и структурирования технической документации, инструкций и внутренних регламентов компании. Платформа предоставляет удобный веб-интерфейс для организации материалов в виде иерархии Книга → Глава → Страница, что упрощает навигацию и поддержание логичной структуры базы знаний.

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

В статье разберём, как установить BookStack на сервер под управлением Ubuntu 24.04.

Как установить BookStack на Ubuntu 24.04

Подготовительные работы

Для обработки HTTP-запросов пользователей и передачи их приложению в качестве веб-сервера в данном руководстве будет использоваться Nginx. Чтобы установить веб-сервер в систему, выполните команду:

$ sudo apt install nginx

Поскольку BookStack разработан на языке PHP, для его работы требуется установленный интерпретатор PHP. На момент написания статьи для корректного функционирования BookStack в системе должна быть установлена версия 8.2 или выше, а также набор расширений, необходимых для работы приложения:

$ sudo apt install php php-fpm php-mysql php-gd php-xml php-mbstring php-curl php-zip php-bcmath php-intl

Чтобы убедиться в том, что в системе установлена версия PHP, удовлетворяющая рекомендации разработчиков BookStack, выполните команду:

$ php -v

Из вывода видно, что в нашем случае BookStack будет использовать PHP версии 8.3.6.

Также для хранения структуры книг, страниц, пользователей и настроек требуется установленный сервер баз данных — MySQL или MariaDB.

Кроме того, для установки необходимых библиотек, требуемых BookStack, используется Composer — менеджер зависимостей для PHP. Его установка на Ubuntu описана в соответствующей статье нашего справочника.

Для загрузки исходного кода BookStack из официального репозитория при инсталляции приложения потребуется Git. Его установка осуществляется с использованием команды:

$ sudo apt install git

Дополнительно для получения удобного доступа со стороны пользователей рекомендуется заранее подготовить имя домена, которое будет указывать на сервер, где устанавливается BookStack. В нашем руководстве будет использоваться доменное имя kb.your-domain-name.ru. Привязка доменного имени к IP-адресу сервера осуществляется при помощи специальной DNS-записи – A-записи. Настройку A-записи можно произвести на сайте-регистраторе домена, либо во вкладке Домены в личном кабинете RUVDS.

Также, чтобы открыть доступ к серверу по протоколам HTTP и HTTPS для подключения к веб-интерфейсу BookStack через браузер, в брандмауэр UFW добавьте следующие правила:

$ sudo ufw allow http
$ sudo ufw allow https

При этом открытие доступа по протоколу HTTPS необходимо непосредственно для подключения к BookStack, а HTTP будет использоваться Центром сертификации при проверке владения доменом перед созданием TLS-сертификата.

Создание базы данных BookStack

Для создания базы данных BookStack подключитесь к командной оболочке MySQL или MariaDB:

$ sudo mysql

При помощи следующего SQL-запроса создайте новую базу данных с именем bookstack_db, которая будет использоваться приложением для хранения данных:

CREATE DATABASE bookstack_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Затем создайте нового пользователя СУБД с именем bookstack_user, который сможет подключаться к серверу базы данных только с локального компьютера. Установите для него достаточно сложный пароль, указав его вместо VeryStrongPassword:

CREATE USER 'bookstack_user'@'localhost' IDENTIFIED BY 'VeryStrongPassword';

Пользователю bookstack_user предоставьте полный набор прав доступа ко всем таблицам базы данных bookstack_db:

GRANT ALL PRIVILEGES ON bookstack_db.* TO 'bookstack_user'@'localhost';

Примените изменения прав доступа:

FLUSH PRIVILEGES;

После чего завершите сеанс работы с консолью MariaDB/MySQL:

EXIT;

Установка BookStack

Создайте каталог, в котором будут размещены файлы веб-интерфейса BookStack:

$ sudo mkdir -p /var/www/bookstack

Измените владельца созданного каталога на текущего пользователя системы, чтобы он имел права на запись внутри данной директории:

$ sudo chown $USER:$USER /var/www/bookstack

Затем перейдите в каталог /var/www/:

$ cd /var/www/

Из официального репозитория GitHub в каталог bookstack/ загрузите исходный код BookStack:

$ git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack

Перейдите в директорию bookstack/:

$ cd bookstack/

Все дальнейшие действия производите, находясь в данном каталоге.

При помощи Composer установите зависимости, необходимые для работы BookStack:

$ composer install --no-dev --prefer-dist

Настройка сайта BookStack

Создайте рабочий файл конфигурации приложения .env из шаблона .env.example, содержащего пример параметров системы:

$ cp .env.example .env

Откройте файл конфигурации:

$ nano .env

Найдите в файле следующие параметры и установите их значения в соответствии с вашими настройками:

APP_URL=https://kb.your-domain-name.ru

DB_HOST=localhost
DB_DATABASE=bookstack_db
DB_USERNAME=bookstack_user
DB_PASSWORD=VeryStrongPassword

Следующей командой сгенерируйте уникальный ключ шифрования приложения с автоматической записью его в файл конфигурации. Данный ключ используется для защиты пользовательских сессий, cookies и других конфиденциальных данных, обрабатываемых системой.

$ php artisan key:generate

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

Следующей командой выполните создание структуры базы данных, необходимой для работы BookStack:

$ php artisan migrate --force

Затем измените владельца всех файлов и каталогов BookStack на системного пользователя www-data, от имени которого работает веб-сервер:

$ sudo chown -R www-data:www-data /var/www/bookstack

Измените права доступа к файлам и каталогам BookStack:

$ sudo chmod -R 755 /var/www/bookstack

Далее запустите вывод на экран содержимого каталога /run/php/:

$ ls /run/php/

Вывод должен показать точное имя сокета PHP-FPM, которое необходимо указать в конфигурации веб-сервера.

После чего откройте конфигурационный файл Nginx, в котором содержатся параметры подключения к сайту BookStack:

$ sudo nano /etc/nginx/sites-available/bookstack

В файле укажите доменное имя, по которому будет доступен сайт BookStack. Также убедитесь в корректности указания имени сокета PHP-FPM из предыдущего шага:

server {
    listen 80;
    server_name kb.your-domain-name.ru;

    root /var/www/bookstack/public;
    index index.php;

    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 ~ /\.ht {
        deny all;
    }
}

Закройте файл с сохранением изменений, после чего создайте символическую ссылку на файл конфигурации сайта в каталоге sites-enabled, тем самым произведя активацию конфигурации сайта в Nginx:

$ sudo ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/

Затем проверьте Nginx на корректность синтаксиса, чтобы избежать ошибок:

$ sudo nginx -t

Вывод команды должен выглядеть следующим образом:

Если ошибок нет, перезапустите конфигурацию веб-сервера:

$ sudo systemctl reload nginx

Настройка HTTPS-доступа к сайту BookStack

При работе с базой знаний пользователи вводят учётные данные, создают и редактируют документы, которые могут содержать конфиденциальную информацию об инфраструктуре компании, сетевых настройках, инструкциях по администрированию и другой служебной информации. Если передача данных осуществляется по протоколу HTTP, то весь трафик передаётся в открытом виде и может быть перехвачен злоумышленниками, имеющими доступ к сетевой инфраструктуре. Использование HTTPS обеспечивает шифрование соединения при помощи TLS (Transport Layer Security). Благодаря этому передаваемые данные становятся недоступными для просмотра третьими лицами.

Для реализации HTTPS-доступа к сайту BookStack используется веб-сервер Nginx. При этом в качестве Центра сертификации удобно использовать сервис Let’s Encrypt, который предоставляет бесплатные TLS-сертификаты. Сертификаты Let’s Encrypt популярны при использовании в корпоративных и публичных проектах благодаря автоматизированному механизму выпуска и продления сертификатов. Получение и установка сертификата выполняется при помощи утилиты Certbot. Данная утилита автоматически настраивает веб-сервер Nginx для работы по HTTPS и создаёт задание на автоматическое продление сертификата.

Следующей командой установите утилиту Certbot и плагин для неё, предназначенный для автоматической настройки Nginx:

$ sudo apt install certbot python3-certbot-nginx

По окончании установки запустите команду, которая инициирует получение и установку TLS-сертификата для сайта BookStack, размещённого на веб-сервере Nginx, с использованием центра сертификации Let’s Encrypt. В команде вместо kb.your-domain-name.ru укажите имя вашего домена:

$ sudo certbot --nginx -d kb.your-domain-name.ru

В ходы работы команды прежде всего выполняется проверка того, что домен указывает на данный сервер. Утилита Certbot подключается к серверам Let’s Encrypt по протоколу ACME и инициирует процедуру выпуска сертификата. Центр сертификации, в свою очередь, отправляет проверочный запрос, чтобы убедиться, что администратор действительно контролирует домен. После успешной проверки Let’s Encrypt выпускает TLS-сертификат. В результате чего утилита Certbot должна внести изменения в конфигурацию Nginx. После внесения изменений Certbot выполняет проверку конфигурации Nginx и перезапускает веб-сервер для применения настроек. Также утилита создаёт задание, которое будет регулярно проверять срок действия сертификата и выполнять его продление.

Подключение к сайту BookStack

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

Доступ к сайту должен осуществляться с использованием протокола HTTPS. Для подключения к веб-интерфейсу базы знаний укажите имя пользователя admin@admin.com с паролем password. Обязательно измените пароль для данной учётной записи сразу после входа на сайт.