Hosting BookStack na Managed VPS: Państwa dokumentacja u Państwa

Co robi BookStack

BookStack to platforma dokumentacyjna pomyślana tak, by pozostać prostą: jego README zakłada natychmiastowe opanowanie, przy podstawowej znajomości edytora tekstu. Państwa zespoły piszą w nim swoje procedury, dokumentację i bazę wiedzy, w przeglądarce, także po polsku, jeśli sobie tego życzą.

• Cztery poziomy porządkowania: półki grupują książki, książki zawierają rozdziały i strony, rozdziały są opcjonalne, a treść żyje na stronach.
• Dwa edytory: edytor wizualny domyślnie oraz edytor Markdown z podglądem na żywo, do których dochodzą schematy diagrams.net.
• Wyszukiwanie: w książce albo we wszystkich książkach, rozdziałach i stronach.
• Uprawnienia: role dla całego systemu oraz uprawnienia właściwe dla półki, książki, rozdziału lub strony.
• Logowanie: e-mail i hasło, OpenID Connect, SAML 2.0, LDAP, z uwierzytelnianiem dwuskładnikowym przez aplikację lub kody zapasowe, które można wymusić dla roli.
• Śledzenie i wymiana: historia rewizji każdej strony, API REST oraz eksport do HTML, PDF, tekstu, Markdown lub przenośnego ZIP.

Projekt trzyma się swoich założeń: jego README zaznacza, że BookStack nie jest pomyślany jako platforma rozszerzalna na inne zastosowania, i pozostaje wierny dokumentacji. Jego renderowanie PDF odbywa się przez dompdf, bez dodatkowej instalacji, z ograniczonymi możliwościami; projekt opisuje inne silniki przez EXPORT_PDF_COMMAND.

Na co pozwala licencja MIT

BookStack jest udostępniany na licencji MIT przez Dana Browna i współtwórców projektu. Zezwala ona na każde użycie, każdą modyfikację i każde rozpowszechnianie, pod jednym warunkiem: w każdej kopii oprogramowania musi pozostać informacja o prawach autorskich i tekst licencji. FAQ projektu wyjaśnia, że to uznanie autorstwa dotyczy kodu, który Państwo udostępniają: nic nie zobowiązuje do wyświetlania nazwy ani logo BookStack na Państwa instancji.

Projekt utrzymuje jedną wersję, wolną i bezpłatną: nie oferuje edycji dla przedsiębiorstw i nie ma oficjalnego hostingu ani planu jego otwarcia. Sprzedaje natomiast plany wsparcia, które współfinansują go razem z darowiznami i patronatami. BookStack instaluje się więc na Państwa serwerze, bez zakupu licencji.

Wymagania BookStack

Docker pozostaje opcjonalny. Projekt nie publikuje oficjalnego obrazu: instalacje w kontenerach pochodzą z projektów społecznościowych, LinuxServer.io i solidnerd. Ten poradnik podąża drogą oficjalną, PHP i MySQL bezpośrednio na serwerze, która nie wymaga niczego więcej.

Dokumentacja odrzuca współdzielony hosting PHP: BookStack wymaga serwera, którym Państwo zarządzają. Nie określa potrzebnej pamięci ani procesora. Na Managed VPS wystarczy opisać nam swoje zastosowanie, liczbę osób oraz objętość obrazów i załączników, a polecimy odpowiedni rozmiar.

Instalacja BookStack

Projekt proponuje dwie drogi: skrypt dla Ubuntu, najkrótszy na nowym serwerze, oraz instalację ręczną dla wszystkich pozostałych przypadków.

Skryptem projektu, na zupełnie nowym 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

Te skrypty są przeznaczone dla świeżo zainstalowanego systemu: mogą nadpisać istniejącą konfigurację WWW. Pomijają też dwa tematy, ustawienia e-mail i bezpieczeństwo systemu, które trzeba przewidzieć osobno.

Skrypt umieszcza BookStack w /var/www/bookstack. Ten dla Ubuntu 26.04 pyta o domenę i adres konta administratora, a na końcu wyświetla wylosowane hasło, nieobecne w jego dzienniku: proszę je zapisać. Przy innym skrypcie proszę odczytać dane dostępowe wyświetlone na końcu i zmienić każdy domyślny dostęp od pierwszego logowania.

Ręcznie, na każdej innej maszynie

Proszę zacząć od bazy danych: jedna baza i użytkownik ograniczony do tej bazy. Skrypt projektu postępuje tak, z wybranym przez Państwa hasłem zamiast 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;"

Następnie proszę pobrać gałąź release, nadać uprawnienia, które dokumentacja podaje dla /var/www/bookstack, i zainstalować zależności:

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

Bazę i adres proszę wpisać w .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

Na koniec proszę skierować katalog główny serwera na katalog public: DocumentRoot w Apache, root w Nginx. Bez Apache albo gdy pliki .htaccess są wyłączone, proszę dodać reguły przepisywania adresów: projekt publikuje przykłady dla Apache i dla Nginx.

Instalacja ręczna otwiera się z kontem admin@admin.com i hasłem password. Adres i hasło proszę zmienić od pierwszego logowania.

HTTPS i APP_URL

Odwiedzający docierają na porty 80 i 443, pod nazwą domeny serwera. Dla tej nazwy proszę utworzyć rekordy A i AAAA, a potem poprosić o certyfikat: skrypt dla Ubuntu 26.04 konfiguruje Apache tylko na porcie 80, a strona instalacji zostawia HTTPS w Państwa rękach. Certbot instaluje certyfikat Let’s Encrypt, dostosowuje Apache i sam odnawia certyfikat. W Nginx proszę zastąpić --apache przez --nginx.

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

Następnie proszę przestawić adres na HTTPS w .env. APP_URL musi dokładnie odpowiadać adresowi, pod którym się wchodzi, łącznie z prefiksem: rozbieżność objawia się brakiem stylów, nadmiernie dużymi ikonami i zepsutymi menu. Adres w https sam włącza bezpieczne ciasteczka.

APP_URL=https://docs.example.com

Jeśli strony już istnieją, ich linki zachowują w bazie stary adres. Proszę wykonać kopię bazy, a potem uruchomić polecenie projektu:

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

BookStack działa w katalogu głównym domeny lub subdomeny, a dokumentacja opisuje też instalację w podkatalogu, jak example.com/bookstack. Jeśli przed Apache dojdzie odwrotne proxy, proszę zadeklarować jego adres w APP_PROXIES: bez tego dziennik audytu i ograniczanie przepustowości widzą adres proxy zamiast adresu odwiedzających. Dokumentacja rezerwuje APP_PROXIES="*" do diagnostyki.

Gdzie mieszkają Państwa dane

Ten sam APP_KEY proszę zachować na stałe i skopiować go. BookStack używa go między innymi do szyfrowania sekretów uwierzytelniania dwuskładnikowego: zmiana może zepsuć te funkcje, a od wersji 26.09 aplikacja zwraca błąd, jeśli go brakuje.

Obrazy są domyślnie publiczne

Przy domyślnym przechowywaniu serwer WWW obsługuje obrazy bezpośrednio, co jest szybkie, a każdy, kto zna ich adres, może je otworzyć. Dla dokumentacji wewnętrznej wyboru dokonuje się w STORAGE_TYPE:

Dla dużych plików trzeba uzgodnić trzy ustawienia: FILE_UPLOAD_SIZE_LIMIT w .env, post_max_size i upload_max_filesize w php.ini oraz client_max_body_size w Nginx, które domyślnie wynosi 1 MB.

Dwa ustawienia liczą się też dla żywej dokumentacji: każda strona domyślnie zachowuje 100 rewizji (REVISION_LIMIT), a kosz przechowuje usunięte elementy przez 30 dni (RECYCLE_BIN_LIFETIME).

E-maile: SMTP i kolejka

BookStack wysyła e-maile w celu potwierdzenia adresów, przy zapomnianym haśle, zaproszeniach i powiadomieniach. Z VPS Simafri wysyłka odbywa się przez uwierzytelniony przekaźnik SMTP, na porcie 587: adres posiadanego już konta pocztowego albo 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

Wynik proszę sprawdzić w „Settings”, „Maintenance”, akcją „Send a Test Email”, która wyświetla napotkane błędy. Błąd przy zaproszeniu pojawia się na ekranie, natomiast błąd powiadomienia pozostaje w dzienniku aplikacji.

Wysyłka w tle

Domyślnie BookStack wysyła e-maile i webhooki w trakcie żądania, co może spowalniać strony. Aby przejść na tło, proszę wpisać QUEUE_CONNECTION=database w .env i uruchomić usługę, według przykładu, który dokumentacja podaje dla instalacji Ubuntu ze skryptu:

[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

Zabezpieczenie instancji BookStack

Dokumentacja bezpieczeństwa podaje listę do wykonania już przy instalacji:

1. Proszę zmienić adres i hasło pierwszego administratora.
2. Proszę sprawdzić, czy serwer WWW obsługuje wyłącznie katalog public, zwłaszcza jeśli BookStack znajduje się w /var/www.
3. Proszę ograniczyć użytkownika bazy do samej bazy BookStack.
4. Proszę wpisać APP_URL, aby adresy generowane przez system nie mogły być manipulowane.
5. Proszę przejrzeć ustawienia rejestracji i dostępu publicznego, a potem role.

Uwierzytelnianie dwuskładnikowe wymusza się następnie dla roli. Proszę też zapisać się na listę mailingową projektu poświęconą bezpieczeństwu, by otrzymywać jego alerty. Adres /status służy do nadzoru: odpowiada 200, gdy wszystko działa, a w przeciwnym razie kodem błędu równym lub wyższym niż 400.

PHP liczy się tak samo jak BookStack. Projekt opublikował 21 października 2026 roku alert o krytycznej aktualizacji PHP, poprawionej w 8.5.12, 8.4.27, 8.3.36 i 8.2.35. Ubuntu publikuje te poprawki pod własnymi numerami pakietów, jak 8.3.6-0ubuntu0.24.04.13 dla Ubuntu 24.04.

Dla Państwa treści proszę zachować filtrowanie włączone domyślnie, a jego złagodzenie zarezerwować dla instancji, na których piszą tylko osoby zaufane. Jeśli konto administratora zostanie utracone, php artisan bookstack:create-admin tworzy kolejne, a php artisan bookstack:reset-mfa usuwa uwierzytelnianie dwuskładnikowe użytkownika.

Kopie zapasowe i aktualizacje

Pełna kopia zapasowa obejmuje bazę i cztery miejsca na pliki właściwe dla Państwa instancji. Eksporty treści służą do czego innego: dokumentacja zaznacza, że nie zastępują kopii zapasowej.

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

Pierwsza linia dotyczy instalacji ze skryptu, gdzie root MySQL łączy się przez sudo; w innych przypadkach proszę wpisać mysqldump -u bookstack -p bookstack. Te dwa pliki proszę przechowywać osobno, najlepiej na innej maszynie. Archiwum zawiera .env, a więc APP_KEY i Państwa hasła: proszę traktować je jak sekret.

Przywracanie

Na nowej maszynie proszę zainstalować BookStack bez uruchamiania php artisan migrate, krok do zakomentowania w skrypcie, jeśli z niego Państwo korzystają, a następnie przywrócić bazę i pliki, zachowując pierwotny APP_KEY:

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

Jeśli zainstalowana wersja jest nowsza niż kopia, proszę następnie uruchomić php artisan migrate. Uprawnienia zapisu serwera WWW na przywróconych katalogach proszę ustawić ponownie. Jeśli adres się zmienił, proszę poprawić APP_URL i uruchomić bookstack:update-url.

Aktualizacja

Przed każdą aktualizacją proszę skopiować bazę i pliki, a następnie, z katalogu BookStack:

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

Skrypt dla Ubuntu 26.04 instaluje BookStack bez Composera. Strona aktualizacji proponuje wtedy, w wersji beta, ./bookstack-system-cli download-vendor zamiast composer install --no-dev. To samo narzędzie potrafi też wykonywać i przywracać kopie, ale projekt nie uważa go jeszcze za gotowe do produkcji: proszę przetestować je, zanim zaczną Państwo na nim polegać.

Dokumentacja prowadzi listę wskazówek właściwych dla każdej wersji, do przeczytania dla wersji docelowej. Kilka przykładów:

• Wersja 26.09: APP_KEY staje się obowiązkowy.
• Wersja 26.05: katalog storage/fonts musi pozostać zapisywalny dla serwera WWW, w przeciwnym razie eksporty PDF mogą się nie udawać.
• Wersja 26.03: po aktualizacji proszę wypróbować wysyłkę e-maili.
• Wersja 25.11: duże zmiany w bazie, których migracja może potrwać kilka minut na dużej instancji.

Luki poprawia się w wersjach konserwacyjnych, jak 26.09.3 z 11 listopada 2026 roku: obrazy i rysunki strony w wersji roboczej lub w koszu pozostawały dostępne i można je było modyfikować, a osobista wersja robocza redaktora mogła stać się widoczna dla innych osób.

Kto za co odpowiada na Managed VPS

Samodzielny hosting wymaga prowadzenia serwera, oprócz samej aplikacji. Na Managed VPS nasze zespoły przejmują serwer i proaktywnie czuwają nad Państwa instancją; BookStack pozostaje Państwa oprogramowaniem, z Państwa ustawieniami i danymi.

Jeśli wolą Państwo, aby nasze zespoły interweniowały w samej aplikacji, usługa ta jest rozliczana godzinowo lub ryczałtowo, z wyceną przekazaną przed interwencją.