Хостване на BookStack на Managed VPS: документацията ви у вас

Какво прави BookStack

BookStack е платформа за документация, замислена да остане проста: README насочва към незабавно овладяване, с обикновени познания за текстообработка. Екипите ви пишат в нея процедурите си, документацията си и базата си знания, в браузър, на български, ако желаят.

• Четири нива на подреждане: рафтовете обединяват книги, книгите носят глави и страници, главите са по желание, а съдържанието живее в страниците.
• Два редактора: визуален редактор по подразбиране и редактор Markdown с преглед на живо, към които се добавят схемите на diagrams.net.
• Търсенето: в една книга или във всички книги, глави и страници.
• Правата: роли за цялата система и разрешения, присъщи на рафт, книга, глава или страница.
• Влизанията: имейл и парола, OpenID Connect, SAML 2.0, LDAP, с двуфакторно удостоверяване чрез приложение или резервни кодове, което може да се наложи по роля.
• Проследяването и обменът: историята на ревизиите на всяка страница, REST API и експорт в HTML, PDF, текст, Markdown или преносим ZIP.

Проектът си признава изборите: README уточнява, че BookStack не е замислен като платформа, разширяема към други употреби, и остава верен на документацията. Изобразяването му в PDF минава през dompdf, без допълнително инсталиране, с ограничени възможности; проектът документира други двигатели с EXPORT_PDF_COMMAND.

Какво позволява лицензът MIT

BookStack е публикуван с лиценз MIT от Dan Brown и сътрудниците на проекта. Той разрешава всякаква употреба, всякаква промяна и всякакво разпространение, при едно условие: да запазите бележката за авторските права и текста на лиценза във всяко копие на софтуера. ЧЗВ на проекта уточнява, че това признание се отнася до кода, който споделяте: нищо не ви задължава да показвате името или логото на BookStack във вашата инстанция.

Проектът поддържа една-единствена, свободна и безплатна версия: не предлага корпоративно издание и няма официален хостинг, нито планове да открие такъв. Продава за сметка на това планове за поддръжка, които допринасят за финансирането му заедно с даренията и спонсорствата. BookStack се инсталира следователно на вашия сървър, без да купувате лиценз.

Изискванията на BookStack

Docker остава по желание. Проектът не публикува официален образ: инсталациите в контейнер идват от проекти на общността, LinuxServer.io и solidnerd. Това ръководство следва официалния път, PHP и MySQL директно на сървъра, който не изисква нищо повече.

Документацията отхвърля споделения PHP хостинг: BookStack изисква сървър, който администрирате вие. Тя не дава числа за нужните памет и процесор. На Managed VPS ни опишете как го използвате, броя на хората и обема на изображенията и прикачените файлове и ще ви препоръчаме подходящия размер.

Инсталиране на BookStack

Проектът предлага два пътя: скрипт за Ubuntu, най-краткият на нов сървър, и ръчно инсталиране за всички останали случаи.

Със скрипта на проекта, върху съвсем нов Ubuntu

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

Тези скриптове са запазени за прясно инсталирана система: могат да презапишат съществуваща уеб конфигурация. Оставят настрана и две теми, настройките на имейла и сигурността на системата, които да предвидите отделно.

Скриптът поставя BookStack в /var/www/bookstack. Този за Ubuntu 26.04 пита за домейна и адреса на администраторския акаунт, после показва накрая случайно генерирана парола, която липсва в журнала му: запишете я. С друг скрипт отбележете достъпите, показани накрая, и сменете всеки достъп по подразбиране още при първото влизане.

На ръка, на всяка друга машина

Започнете с базата данни: една база и потребител, ограничен до тази база. Скриптът на проекта процедира така, с паролата по ваш избор вместо change-me:

sudo mysql -u root --execute="CREATE DATABASE bookstack;"
sudo mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'change-me';"
sudo mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;"

Изтеглете после клона release, задайте правата, които документацията дава за /var/www/bookstack, после инсталирайте зависимостите:

cd /var/www
sudo git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
sudo chown -R $USER:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
cd bookstack
composer install --no-dev
cp .env.example .env
sudo chmod 640 .env

Въведете базата и адреса в .env:

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=change-me

php artisan key:generate
php artisan migrate

Насочете накрая уеб корена към папката public: DocumentRoot в Apache, root в Nginx. Без Apache или когато файловете .htaccess са изключени, добавете правилата за пренаписване на адреси: проектът публикува примери за Apache и за Nginx.

Ръчното инсталиране се отваря с акаунта admin@admin.com и паролата password. Сменете адреса и паролата още при първото влизане.

HTTPS и APP_URL

Посетителите пристигат на портове 80 и 443, на името на домейна на сървъра. Създайте за това име записи A и AAAA, после поискайте сертификата: скриптът за Ubuntu 26.04 конфигурира Apache само на порт 80, а страницата за инсталиране оставя HTTPS на вас. Certbot поставя сертификата Let's Encrypt, приспособява Apache и сам подновява сертификата. При Nginx заменете --apache с --nginx.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --apache -d docs.example.com

Сменете после адреса на HTTPS в .env. APP_URL трябва да съответства точно на адреса за посещение, включително префикса: разминаването се познава по липсващи стилове, непропорционални икони и счупени менюта. Адрес с https сам включва защитените бисквитки.

APP_URL=https://docs.example.com

Ако страници вече съществуват, връзките им запазват стария адрес в базата. Архивирайте базата, после изпълнете командата на проекта:

php artisan bookstack:update-url http://docs.example.com https://docs.example.com

BookStack се предоставя в корена на домейн или поддомейн, а документацията описва и инсталиране в подпапка, като example.com/bookstack. Ако пред Apache се добави обратен прокси, декларирайте адреса му в APP_PROXIES: без него одитният журнал и ограничаването на скоростта виждат адреса на проксито вместо този на посетителите. Документацията резервира APP_PROXIES="*" за диагностика.

Къде живеят данните ви

Пазете един и същ APP_KEY във времето и го архивирайте. BookStack го използва, за да шифрова по-специално тайните на двуфакторното удостоверяване: смяната му може да развали тези функции, а от версия 26.09 приложението връща грешка, ако липсва.

Изображенията са публични по подразбиране

Със съхранението по подразбиране уеб сървърът обслужва изображенията директно, което е бързо, и всеки, който знае адреса им, може да ги отвори. За вътрешна документация изборът се прави в STORAGE_TYPE:

За тежките файлове три настройки трябва да са съгласувани: FILE_UPLOAD_SIZE_LIMIT в .env, post_max_size и upload_max_filesize в php.ini и client_max_body_size в Nginx, който е 1 MB по подразбиране.

Две настройки са важни и за жива документация: всяка страница пази 100 ревизии по подразбиране (REVISION_LIMIT), а кошчето съхранява изтритите елементи 30 дни (RECYCLE_BIN_LIFETIME).

Имейлите: SMTP и опашка

BookStack изпраща имейли за потвърждение на адресите, забравена парола, покани и известия. От VPS на Simafri изпращането минава през удостоверено SMTP реле, на порт 587: адресът на пощенски акаунт, който вече имате, или Simafri Suite.

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=change-me
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME=BookStack

Проверете резултата в „Settings“, „Maintenance“, с действието „Send a Test Email“, което показва срещнатите грешки. Неуспех при покана се показва на екрана, докато неуспех при известие остава в журнала на приложението.

Изпращане във фонов режим

По подразбиране BookStack изпраща имейли и webhooks по време на заявката, което може да забави страниците. За да минете във фонов режим, запишете QUEUE_CONNECTION=database в .env и пуснете услуга, с примера, който документацията дава за инсталация на Ubuntu чрез скрипт:

[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bookstack-queue.service
sudo systemctl start bookstack-queue.service

Защита на инстанцията BookStack

Документацията за сигурност дава списък, който да изпълните още при инсталирането:

1. Сменете адреса и паролата на първия администратор.
2. Проверете дали уеб сървърът обслужва единствено папката public, особено ако BookStack живее под /var/www.
3. Ограничете потребителя на базата до единствената база на BookStack.
4. Въведете APP_URL, за да не могат адресите, генерирани от системата, да бъдат манипулирани.
5. Прегледайте настройките за регистрация и публичен достъп, после ролите.

Двуфакторното удостоверяване се налага после по роли. Абонирайте се и за пощенския списък за сигурност на проекта, за да получавате предупрежденията му. Адресът /status служи за наблюдение: отговаря 200, когато всичко е наред, и код за грешка, равен или по-голям от 400, в противен случай.

PHP е също толкова важен, колкото BookStack. Проектът публикува на 21 октомври 2026 г. предупреждение за критично обновяване на PHP, поправено в 8.5.12, 8.4.27, 8.3.36 и 8.2.35. Ubuntu публикува тези поправки под собствени номера на пакети, като 8.3.6-0ubuntu0.24.04.13 за Ubuntu 24.04.

За съдържанието ви оставете филтрирането, включено по подразбиране, и резервирайте облекчаването му за инстанции, в които пишат само доверени хора. Ако администраторски акаунт се загуби, php artisan bookstack:create-admin създава друг, а php artisan bookstack:reset-mfa премахва двуфакторното удостоверяване на потребител.

Резервни копия и обновления

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

sudo mysqldump -u root bookstack > bookstack.backup.sql
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

Първият ред е за инсталация чрез скрипт, където root на MySQL се свързва чрез sudo; другаде напишете mysqldump -u bookstack -p bookstack. Съхранете тези два файла отделно, за предпочитане на друга машина. Архивът съдържа .env, следователно APP_KEY и паролите ви: третирайте го като тайна.

Възстановяване

На нова машина инсталирайте BookStack, без да изпълнявате php artisan migrate, стъпка, която да коментирате в скрипта, ако го използвате, после възстановете базата и файловете, като запазите първоначалния APP_KEY:

sudo mysql -u root bookstack < bookstack.backup.sql
tar -xvzf bookstack-files-backup.tar.gz

Ако инсталираната версия е по-нова от резервното копие, изпълнете после php artisan migrate. Върнете правата за запис на уеб сървъра върху възстановените папки. Ако адресът се е променил, поправете APP_URL и изпълнете bookstack:update-url.

Обновяване

Архивирайте базата и файловете преди всяко обновяване, после, от папката на BookStack:

git pull origin release
composer install --no-dev
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear

Скриптът за Ubuntu 26.04 инсталира BookStack без Composer. Страницата с обновления предлага тогава, в бета, ./bookstack-system-cli download-vendor вместо composer install --no-dev. Същият този инструмент умее да архивира и възстановява, но проектът още не го смята за готов за продукция: тествайте го, преди да му се доверите.

Документацията поддържа списък с указания, присъщи на всяка версия, които да прочетете за целевата версия. Няколко примера:

• Версия 26.09: APP_KEY става задължителен.
• Версия 26.05: папката storage/fonts трябва да остане достъпна за запис от уеб сървъра, иначе експортите в PDF могат да пропаднат.
• Версия 26.03: изпробвайте изпращането на имейли след обновяването.
• Версия 25.11: големи промени в базата, чиято миграция може да отнеме няколко минути в голяма инстанция.

Пробивите се поправят във версии за поддръжка, като 26.09.3 от 11 ноември 2026 г.: изображенията и чертежите на страница чернова или в кошчето оставаха достъпни и можеха да се променят, а личната чернова на редактор можеше да стане видима за други хора.

Кой какво прави на Managed VPS

Самостоятелното хостване изисква да поддържате сървъра освен приложението. На Managed VPS нашите екипи поемат сървъра и следят проактивно вашата инстанция; BookStack остава ваш софтуер, с неговите настройки и данни.

Ако предпочитате нашите екипи да се намесват в самото приложение, тази услуга се фактурира на час или на фиксирана цена, с оферта, съобщена преди намесата.