Hostovat BookStack na Managed VPS: vaše dokumentace u vás

Co BookStack umí

BookStack je dokumentační platforma navržená tak, aby zůstala jednoduchá: její README míří na okamžité zvládnutí, s prostými znalostmi textového editoru. Vaše týmy v ní v prohlížeči píšou své postupy, dokumentaci a znalostní bázi, v češtině, pokud si to přejí.

• Čtyři úrovně uspořádání: police sdružují knihy, knihy nesou kapitoly a stránky, kapitoly jsou nepovinné a obsah žije ve stránkách.
• Dva editory: výchozí vizuální editor a editor Markdown s živým náhledem, k nimž přibývají schémata diagrams.net.
• Vyhledávání: v jedné knize, nebo napříč všemi knihami, kapitolami a stránkami.
• Práva: role pro celý systém a oprávnění specifická pro polici, knihu, kapitolu nebo stránku.
• Přihlašování: e-mail a heslo, OpenID Connect, SAML 2.0, LDAP, s dvoufázovým ověřením pomocí aplikace nebo záložních kódů, které lze vynutit podle role.
• Sledování a výměny: historie revizí každé stránky, API REST a export do HTML, PDF, textu, Markdownu nebo přenosného ZIP.

Projekt si za svými volbami stojí: jeho README upřesňuje, že BookStack není navržen jako platforma rozšiřitelná k jiným použitím, a zůstává věrný dokumentaci. Jeho vykreslování PDF probíhá přes dompdf, bez další instalace, s omezenými možnostmi; projekt dokumentuje další nástroje pomocí EXPORT_PDF_COMMAND.

Co dovoluje licence MIT

BookStack je vydáván pod licencí MIT Danem Brownem a přispěvateli projektu. Dovoluje jakékoli použití, úpravy i šíření, za jediné podmínky: ve všech kopiích softwaru zachovat upozornění na autorská práva a text licence. FAQ projektu upřesňuje, že se tato atribuce týká kódu, který sdílíte: nic vás nenutí zobrazovat na vaší instanci název nebo logo BookStack.

Projekt vede jedinou, svobodnou a bezplatnou verzi: nenabízí podnikovou edici a nemá oficiální hosting ani plán ho otevřít. Prodává naopak tarify podpory, které spolu s dary a sponzory přispívají k jeho financování. BookStack se tedy instaluje na váš server, aniž byste kupovali licenci.

Požadavky BookStack

Docker zůstává nepovinný. Projekt nezveřejňuje oficiální obraz: instalace v kontejnerech pocházejí z komunitních projektů, LinuxServer.io a solidnerd. Tento průvodce sleduje oficiální cestu, PHP a MySQL přímo na serveru, která nevyžaduje nic dalšího.

Dokumentace nedoporučuje sdílený hosting PHP: BookStack vyžaduje server, který spravujete. Nároky na paměť ani procesor neuvádí. Na Managed VPS nám popište své využití, počet lidí a objem obrázků a příloh a doporučíme vám vhodnou velikost.

Instalace BookStack

Projekt nabízí dvě cesty: skript pro Ubuntu, nejkratší na novém serveru, a ruční instalaci pro všechny ostatní případy.

Se skriptem projektu, na zcela novém 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

Tyto skripty jsou určeny pro čerstvě nainstalovaný systém: mohou přepsat stávající konfiguraci webu. Vynechávají také dvě témata, nastavení e-mailů a zabezpečení systému, která je třeba zajistit zvlášť.

Skript umístí BookStack do /var/www/bookstack. Skript pro Ubuntu 26.04 se zeptá na doménu a adresu účtu správce a na konci zobrazí náhodně vygenerované heslo, které není v jeho protokolu: poznamenejte si ho. U jiného skriptu si zapište přístupové údaje zobrazené na konci a každý výchozí přístup změňte hned při prvním přihlášení.

Ručně, na jakémkoli jiném stroji

Začněte databází: jedna databáze a uživatel omezený na tuto databázi. Skript projektu postupuje takto, s heslem podle vašeho výběru místo 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;"

Poté stáhněte větev release, nastavte práva, která dokumentace uvádí pro /var/www/bookstack, a nainstalujte 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

Do .env doplňte databázi a adresu:

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

Nakonec nasměrujte webový kořen na složku public: DocumentRoot v Apache, root v Nginx. Bez Apache, nebo když jsou soubory .htaccess vypnuté, přidejte pravidla pro přepisování adres: projekt zveřejňuje příklady pro Apache i pro Nginx.

Ruční instalace se otevírá s účtem admin@admin.com a heslem password. Adresu i heslo změňte hned při prvním přihlášení.

HTTPS a APP_URL

Návštěvníci přicházejí na porty 80 a 443, pod doménovým jménem serveru. Vytvořte pro toto jméno záznamy A a AAAA a pak požádejte o certifikát: skript pro Ubuntu 26.04 nastavuje Apache jen na portu 80 a instalační stránka ponechává HTTPS na vás. Certbot nainstaluje certifikát Let's Encrypt, upraví Apache a certifikát sám obnovuje. U 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

Poté přepněte adresu v .env na HTTPS. APP_URL musí přesně odpovídat adrese, na kterou se chodí, včetně předpony: odchylka se projeví chybějícími styly, nepřiměřeně velkými ikonami a rozbitými nabídkami. Adresa v https sama zapíná zabezpečené cookies.

APP_URL=https://docs.example.com

Pokud už stránky existují, jejich odkazy zůstávají v databázi se starou adresou. Zálohujte databázi a pak spusťte příkaz projektu:

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

BookStack se obsluhuje v kořeni domény nebo subdomény a dokumentace popisuje i instalaci do podsložky, například example.com/bookstack. Pokud se před Apache přidá reverzní proxy, uveďte její adresu v APP_PROXIES: bez ní vidí auditní protokol a omezení rychlosti adresu proxy místo adresy návštěvníků. Dokumentace vyhrazuje APP_PROXIES="*" pro diagnostiku.

Kde žijí vaše data

Ponechte stejný APP_KEY dlouhodobě a zálohujte ho. BookStack jím šifruje mimo jiné tajné údaje dvoufázového ověření: jeho změna může tyto funkce rozbít a od verze 26.09 aplikace vrací chybu, pokud chybí.

Obrázky jsou ve výchozím nastavení veřejné

Při výchozím úložišti obsluhuje obrázky přímo webový server, což je rychlé, a otevřít je může každý, kdo zná jejich adresu. Pro interní dokumentaci se volba dělá v STORAGE_TYPE:

U velkých souborů se musí shodnout tři nastavení: FILE_UPLOAD_SIZE_LIMIT v .env, post_max_size a upload_max_filesize v php.ini a client_max_body_size v Nginx, které je ve výchozím nastavení 1 MB.

Dvě nastavení záleží i u živé dokumentace: každá stránka uchovává ve výchozím nastavení 100 revizí (REVISION_LIMIT) a koš uchovává smazané položky 30 dní (RECYCLE_BIN_LIFETIME).

E-maily: SMTP a fronta

BookStack odesílá e-maily pro potvrzení adres, zapomenuté heslo, pozvánky a oznámení. Z VPS Simafri vede odesílání přes ověřené relé SMTP na portu 587: adresa poštovního účtu, který už máte, nebo 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ýsledek ověřte v „Settings“, „Maintenance“, akcí „Send a Test Email“, která zobrazí nalezené chyby. Selhání při pozvánce se zobrazí na obrazovce, zatímco selhání oznámení zůstane v protokolu aplikace.

Odesílání na pozadí

Ve výchozím nastavení BookStack odesílá e-maily a webhooky během požadavku, což může stránky zpomalit. Chcete-li přejít na pozadí, zapište do .env QUEUE_CONNECTION=database a spusťte službu, podle příkladu, který dokumentace uvádí pro instalaci Ubuntu pomocí skriptu:

[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čení vaší instance BookStack

Bezpečnostní dokumentace uvádí seznam, který je třeba projít hned při instalaci:

1. Změňte adresu a heslo prvního správce.
2. Ověřte, že webový server obsluhuje jedinou složku public, zvlášť pokud BookStack žije pod /var/www.
3. Omezte uživatele databáze na jedinou databázi BookStack.
4. Vyplňte APP_URL, aby adresy generované systémem nešlo zmanipulovat.
5. Zkontrolujte nastavení registrace a veřejného přístupu a poté role.

Dvoufázové ověření se pak vynucuje podle role. Přihlaste se také k bezpečnostnímu rozesílacímu seznamu projektu, abyste dostávali jeho upozornění. Adresa /status slouží k dohledu: odpovídá 200, když je všechno v pořádku, a jinak chybovým kódem rovným 400 nebo vyšším.

PHP záleží stejně jako BookStack. Projekt zveřejnil 21. října 2026 upozornění na kritickou aktualizaci PHP, opravenou ve verzích 8.5.12, 8.4.27, 8.3.36 a 8.2.35. Ubuntu zveřejňuje tyto opravy pod vlastními čísly balíčků, například 8.3.6-0ubuntu0.24.04.13 pro Ubuntu 24.04.

U svého obsahu ponechte filtrování zapnuté ve výchozím nastavení a jeho uvolnění vyhraďte pro instance, kde píší jen důvěryhodní lidé. Pokud se ztratí účet správce, php artisan bookstack:create-admin vytvoří další a php artisan bookstack:reset-mfa odebere uživateli dvoufázové ověření.

Zálohy a aktualizace

Úplná záloha zahrnuje databázi a čtyři umístění souborů vlastní vaší instanci. Exporty obsahu slouží jinému účelu: dokumentace upřesňuje, že zálohu nenahrazují.

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

První řádek míří na instalaci pomocí skriptu, kde se root MySQL připojuje přes sudo; jinde napište mysqldump -u bookstack -p bookstack. Tyto dva soubory uložte zvlášť, nejlépe na jiném stroji. Archiv obsahuje .env, tedy APP_KEY a vaše hesla: zacházejte s ním jako s tajemstvím.

Obnova

Na novém stroji nainstalujte BookStack bez spuštění php artisan migrate, což je krok, který je třeba ve skriptu zakomentovat, pokud ho používáte, a pak obnovte databázi a soubory, přičemž ponechte původní APP_KEY:

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

Pokud je nainstalovaná verze novější než záloha, spusťte poté php artisan migrate. Vraťte webovému serveru práva zápisu na obnovené složky. Pokud se změnila adresa, opravte APP_URL a spusťte bookstack:update-url.

Aktualizace

Před každou aktualizací zálohujte databázi i soubory a poté, ze složky 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 pro Ubuntu 26.04 instaluje BookStack bez Composeru. Stránka aktualizací pak místo composer install --no-dev nabízí, v betě, ./bookstack-system-cli download-vendor. Tento nástroj umí také zálohovat a obnovovat, ale projekt jej zatím nepovažuje za připravený pro produkci: vyzkoušejte jej, než se na něj spolehnete.

Dokumentace vede seznam pokynů specifických pro každou verzi, které je třeba si přečíst pro cílovou verzi. Několik příkladů:

• Verze 26.09: APP_KEY se stává povinným.
• Verze 26.05: složka storage/fonts musí zůstat pro webový server zapisovatelná, jinak mohou exporty PDF selhat.
• Verze 26.03: po aktualizaci vyzkoušejte odesílání e-mailů.
• Verze 25.11: velké změny databáze, jejichž migrace může na velké instanci trvat několik minut.

Chyby se opravují v údržbových verzích, například 26.09.3 z 11. listopadu 2026: obrázky a kresby stránky v konceptu nebo v koši zůstávaly dostupné a šly upravit a osobní koncept editora se mohl zobrazit dalším lidem.

Kdo co dělá na Managed VPS

Vlastní hosting vyžaduje, abyste kromě aplikace udržovali i server. Na Managed VPS se serveru ujímají naše týmy a vaši instanci proaktivně sledují; BookStack zůstává vaším softwarem, s jeho nastavením a daty.

Pokud dáváte přednost tomu, aby naše týmy zasáhly přímo v aplikaci, tato služba se účtuje po hodinách nebo paušálem, s cenovou nabídkou sdělenou před zásahem.