Hostovanie BookStack na Managed VPS: vaša dokumentácia u vás doma

Čo BookStack robí

BookStack je dokumentačná platforma navrhnutá tak, aby zostala jednoduchá: jeho README cieli na okamžité osvojenie, so základnými pojmami textového editora. Vaše tímy v ňom píšu svoje postupy, dokumentáciu a znalostnú databázu, v prehliadači, aj po slovensky, ak si to želajú.

• Štyri úrovne usporiadania: police združujú knihy, knihy nesú kapitoly a stránky, kapitoly sú voliteľné a obsah žije na stránkach.
• Dva editory: predvolený vizuálny editor a editor Markdown so živým náhľadom, ku ktorým pribúdajú schémy diagrams.net.
• Vyhľadávanie: v rámci knihy alebo naprieč všetkými knihami, kapitolami a stránkami.
• Práva: roly pre celý systém a oprávnenia špecifické pre policu, knihu, kapitolu alebo stránku.
• Prihlasovanie: e-mail a heslo, OpenID Connect, SAML 2.0, LDAP, s dvojfaktorovým overením aplikáciou alebo záložnými kódmi, ktoré možno vynútiť podľa roly.
• Sledovanie a výmeny: história revízií každej stránky, API REST a export do HTML, PDF, textu, Markdown alebo prenosného ZIP.

Projekt si svoje voľby stojí za slovom: jeho README upresňuje, že BookStack nie je navrhnutý ako platforma rozšíriteľná na iné použitia, a zostáva verný dokumentácii. Jeho vykresľovanie PDF prebieha cez dompdf, bez ďalšej inštalácie, s obmedzenými možnosťami; projekt dokumentuje ďalšie nástroje cez EXPORT_PDF_COMMAND.

Čo umožňuje licencia MIT

BookStack vychádza pod licenciou MIT, ktorú vydali Dan Brown a prispievatelia projektu. Dovoľuje akékoľvek použitie, úpravu a šírenie, s jednou podmienkou: v každej kópii softvéru zachovať upozornenie o autorských právach a text licencie. FAQ projektu upresňuje, že táto atribúcia sa týka kódu, ktorý zdieľate: nič vás nenúti zobrazovať názov alebo logo BookStack na vašej inštancii.

Projekt vedie jedinú, slobodnú a bezplatnú verziu: neponúka podnikovú edíciu a nemá oficiálne hostovanie ani plán ho otvoriť. Predáva však plány podpory, ktoré spolu s darmi a sponzorstvom prispievajú k jeho financovaniu. BookStack sa teda inštaluje na váš server, bez licencie, ktorú by ste museli kupovať.

Požiadavky BookStack

Docker zostáva voliteľný. Projekt nezverejňuje oficiálny obraz: inštalácie v kontajneri pochádzajú z komunitných projektov, LinuxServer.io a solidnerd. Tento sprievodca sleduje oficiálnu cestu, PHP a MySQL priamo na serveri, ktorá nevyžaduje nič viac.

Dokumentácia vylučuje zdieľaný hosting PHP: BookStack vyžaduje server, ktorý spravujete. Neuvádza potrebnú pamäť ani procesor. Na spravovanom VPS (Managed VPS) nám opíšte svoje použitie, počet ľudí a objem obrázkov a príloh a odporučíme vám vhodnú veľkosť.

Inštalácia BookStack

Projekt ponúka dve cesty: skript pre Ubuntu, najkratší na novom serveri, a ručnú inštaláciu pre všetky ostatné prípady.

So skriptom projektu, na úplne novom 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

Tieto skripty sú vyhradené pre čerstvo nainštalovaný systém: môžu prepísať existujúcu webovú konfiguráciu. Vynechávajú aj dve témy, nastavenie e-mailov a zabezpečenie systému, ktoré treba riešiť osobitne.

Skript umiestni BookStack do /var/www/bookstack. Skript pre Ubuntu 26.04 sa opýta na doménu a adresu účtu správcu a na konci zobrazí náhodne vygenerované heslo, ktoré sa nenachádza v jeho zázname: poznačte si ho. S iným skriptom si zapíšte prístupové údaje zobrazené na konci a každý predvolený prístup zmeňte pri prvom prihlásení.

Ručne, na akomkoľvek inom stroji

Začnite databázou: jedna databáza a používateľ obmedzený na túto databázu. Skript projektu postupuje takto, s heslom podľa vášho výberu namiesto 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;"

Potom stiahnite vetvu release, nastavte práva, ktoré dokumentácia uvádza pre /var/www/bookstack, a nainštalujte závislosti:

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

Vyplňte databázu a adresu v .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

Nakoniec nasmerujte webový koreň na priečinok public: DocumentRoot v Apache, root v Nginx. Bez Apache, alebo keď sú súbory .htaccess vypnuté, pridajte pravidlá prepisovania adries: projekt zverejňuje príklady pre Apache aj pre Nginx.

Ručná inštalácia sa otvára s účtom admin@admin.com a heslom password. Adresu aj heslo zmeňte pri prvom prihlásení.

HTTPS a APP_URL

Návštevníci prichádzajú na porty 80 a 443, pod doménovým menom servera. Vytvorte pre toto meno záznamy A a AAAA a potom si vyžiadajte certifikát: skript pre Ubuntu 26.04 nastavuje Apache len na porte 80 a inštalačná stránka nechá HTTPS na vás. Certbot nainštaluje certifikát Let’s Encrypt, upraví Apache a certifikát si následne obnovuje sám. Pri Nginx nahraďte --apache za --nginx.

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

Potom prepnite adresu na HTTPS v .env. APP_URL musí presne zodpovedať adrese návštevy, vrátane predpony: nezhoda sa prejaví chýbajúcimi štýlmi, neprimerane veľkými ikonami a rozbitými menu. Adresa v https aktivuje zabezpečené cookies sama.

APP_URL=https://docs.example.com

Ak už stránky existujú, ich odkazy majú v databáze starú adresu. Zálohujte databázu a potom spustite príkaz projektu:

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

BookStack sa obsluhuje v koreni domény alebo subdomény a dokumentácia opisuje aj inštaláciu pod podpriečinkom, ako example.com/bookstack. Ak sa pred Apache pridá reverzná proxy, deklarujte jej adresu v APP_PROXIES: bez nej vidí auditný záznam a obmedzenie rýchlosti adresu proxy namiesto adresy návštevníkov. Dokumentácia vyhradzuje APP_PROXIES="*" na diagnostiku.

Kde žijú vaše údaje

Ponechajte rovnaký APP_KEY dlhodobo a zálohujte ho. BookStack ním šifruje okrem iného tajomstvá dvojfaktorového overenia: jeho zmena môže tieto funkcie pokaziť a od verzie 26.09 aplikácia vráti chybu, ak chýba.

Obrázky sú predvolene verejné

Pri predvolenom úložisku obsluhuje obrázky priamo webový server, čo je rýchle, a ktokoľvek, kto pozná ich adresu, ich môže otvoriť. Pre internú dokumentáciu sa voľba robí v STORAGE_TYPE:

Pri veľkých súboroch sa musia zladiť tri nastavenia: FILE_UPLOAD_SIZE_LIMIT v .env, post_max_size a upload_max_filesize v php.ini a client_max_body_size v Nginx, ktoré predvolene platí 1 MB.

Dve nastavenia dôležité aj pre živú dokumentáciu: každá stránka predvolene uchováva 100 revízií (REVISION_LIMIT) a kôš uchováva odstránené položky 30 dní (RECYCLE_BIN_LIFETIME).

E-maily: SMTP a fronta

BookStack odosiela e-maily na potvrdenie adries, zabudnuté heslo, pozvánky a notifikácie. Z VPS Simafri odosielanie prechádza cez overené relé SMTP na porte 587: adresa poštového účtu, ktorý už máte, alebo 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

Výsledok overte v „Settings“, „Maintenance“, akciou „Send a Test Email“, ktorá zobrazí zistené chyby. Zlyhanie pri pozvánke sa zobrazí na obrazovke, kým zlyhanie notifikácie zostáva v zázname aplikácie.

Odosielanie na pozadí

Predvolene BookStack odosiela e-maily a webhooky počas požiadavky, čo môže spomaliť stránky. Na prechod na pozadie zapíšte do .env QUEUE_CONNECTION=database a spustite službu, podľa príkladu, ktorý dokumentácia uvádza pre inštaláciu Ubuntu cez skript:

[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

Zabezpečenie vašej inštancie BookStack

Bezpečnostná dokumentácia uvádza zoznam, ktorý treba prejsť hneď po inštalácii:

1. Zmeňte adresu a heslo prvého správcu.
2. Overte, že webový server obsluhuje iba priečinok public, najmä ak BookStack žije pod /var/www.
3. Obmedzte používateľa databázy iba na databázu BookStack.
4. Vyplňte APP_URL, aby sa adresy generované systémom nedali zmanipulovať.
5. Prejdite nastavenia registrácie a verejného prístupu a potom roly.

Dvojfaktorové overenie sa potom vynucuje podľa roly. Prihláste sa aj do bezpečnostného e-mailového zoznamu projektu, aby ste dostávali jeho upozornenia. Adresa /status slúži na dohľad: odpovedá 200, keď je všetko v poriadku, a v opačnom prípade chybovým kódom 400 alebo vyšším.

PHP je rovnako dôležité ako BookStack. Projekt zverejnil 21. októbra 2026 upozornenie na kritickú aktualizáciu PHP, opravenú vo verziách 8.5.12, 8.4.27, 8.3.36 a 8.2.35. Ubuntu zverejňuje tieto opravy pod vlastnými číslami balíkov, ako 8.3.6-0ubuntu0.24.04.13 pre Ubuntu 24.04.

Pre svoj obsah ponechajte predvolene zapnuté filtrovanie a jeho uvoľnenie vyhraďte pre inštancie, kde píšu len dôveryhodní ľudia. Ak sa účet správcu stratí, php artisan bookstack:create-admin vytvorí ďalší a php artisan bookstack:reset-mfa odoberie používateľovi dvojfaktorové overenie.

Zálohy a aktualizácie

Úplná záloha zahŕňa databázu a štyri umiestnenia súborov špecifické pre vašu inštanciu. Exporty obsahu slúžia na niečo iné: dokumentácia upresňuje, že zálohu nenahrádzajú.

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

Prvý riadok cieli na inštaláciu cez skript, kde sa root v MySQL pripája cez sudo; inde napíšte mysqldump -u bookstack -p bookstack. Tieto dva súbory uložte osobitne, najlepšie na inom stroji. Archív obsahuje .env, teda APP_KEY a vaše heslá: zaobchádzajte s ním ako s tajomstvom.

Obnova

Na novom stroji nainštalujte BookStack bez spustenia php artisan migrate, čo je krok, ktorý treba v skripte zakomentovať, ak ho používate, a potom obnovte databázu a súbory, pričom ponechajte pôvodný APP_KEY:

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

Ak je nainštalovaná verzia novšia než záloha, potom spustite php artisan migrate. Vráťte webovému serveru práva na zápis do obnovených priečinkov. Ak sa adresa zmenila, opravte APP_URL a spustite bookstack:update-url.

Aktualizácia

Pred každou aktualizáciou zálohujte databázu a súbory a potom, z priečinka BookStack:

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

Skript pre Ubuntu 26.04 inštaluje BookStack bez Composeru. Stránka aktualizácií potom v beta verzii ponúka ./bookstack-system-cli download-vendor namiesto composer install --no-dev. Ten istý nástroj vie zálohovať aj obnovovať, projekt ho však zatiaľ nepovažuje za pripravený na produkciu: vyskúšajte ho, než sa naň spoľahnete.

Dokumentácia vedie zoznam pokynov špecifických pre každú verziu, ktoré si treba prečítať pre cieľovú verziu. Niekoľko príkladov:

• Verzia 26.09: APP_KEY sa stáva povinným.
• Verzia 26.05: priečinok storage/fonts musí zostať zapisovateľný pre webový server, inak môžu exporty PDF zlyhať.
• Verzia 26.03: po aktualizácii vyskúšajte odosielanie e-mailov.
• Verzia 25.11: veľké zmeny v databáze, ktorých migrácia môže na veľkej inštancii trvať niekoľko minút.

Chyby sa opravujú v udržiavacích verziách, ako 26.09.3 z 11. novembra 2026: obrázky a kresby stránky v koncepte alebo v koši zostávali dostupné a dali sa upravovať a osobný koncept editora sa mohol zobraziť iným osobám.

Kto čo robí na Managed VPS

Hostovanie na vlastnom serveri vyžaduje popri aplikácii starať sa aj o server. Na Managed VPS preberajú server naše tímy a vašu inštanciu proaktívne sledujú; BookStack zostáva vaším softvérom, s vašimi nastaveniami a údajmi.

Ak by ste uprednostnili, aby naše tímy zasiahli priamo v aplikácii, táto služba sa fakturuje hodinovo alebo paušálne, s cenovou ponukou oznámenou pred zásahom.