BookStack hosztolása Managed VPS-en: dokumentációja a saját szerverén

Mit tud a BookStack

A BookStack egy egyszerűségre törekvő dokumentációs platform: a README azonnali használatbavételt céloz, egyszerű szövegszerkesztői ismeretekkel. A csapatai itt írják meg az eljárásaikat, a dokumentációjukat és a tudásbázisukat, egy böngészőben, magyarul is, ha úgy szeretnék.

• Négy rendezési szint: a polcok könyveket fognak össze, a könyvek fejezeteket és oldalakat hordoznak, a fejezetek elhagyhatók, a tartalom az oldalakban él.
• Két szerkesztő: alapértelmezésként egy vizuális szerkesztő, és egy Markdown-szerkesztő élő előnézettel, amelyekhez a diagrams.net sémák társulnak.
• A keresés: egy könyvön belül, vagy az összes könyvben, fejezetben és oldalban.
• A jogosultságok: szerepkörök az egész rendszerre, és egy polcra, könyvre, fejezetre vagy oldalra vonatkozó saját jogosultságok.
• A bejelentkezések: e-mail és jelszó, OpenID Connect, SAML 2.0, LDAP, alkalmazással vagy tartalékkódokkal működő kétlépcsős hitelesítéssel, amelyet szerepkörönként elő lehet írni.
• A követés és a csere: minden oldal változatainak előzményei, egy REST API, valamint az export HTML, PDF, szöveg, Markdown vagy hordozható ZIP formátumba.

A projekt vállalja a döntéseit: a README leszögezi, hogy a BookStack nem más felhasználások felé bővíthető platformnak készült, és a dokumentációhoz kötött marad. A PDF-megjelenítése a dompdf-en keresztül megy, további telepítés nélkül, korlátozott képességekkel; a projekt más motorokat is dokumentál az EXPORT_PDF_COMMAND változóval.

Mit enged meg az MIT licenc

A BookStack MIT licenc alatt jelenik meg, Dan Brown és a projekt közreműködői által. Minden használatot, módosítást és terjesztést engedélyez, egyetlen feltétellel: a szerzői jogi megjelölést és a licenc szövegét meg kell tartani a szoftver minden másolatában. A projekt GYIK-je pontosítja, hogy ez a feltüntetés az Ön által megosztott kódra vonatkozik: semmi sem kötelezi, hogy a BookStack nevét vagy logóját megjelenítse a példányán.

A projekt egyetlen, szabad és ingyenes verziót tart fenn: nem kínál vállalati kiadást, és nincs hivatalos tárhelyszolgáltatása, sem terve, hogy nyisson egyet. Ellenben támogatási csomagokat árul, amelyek az adományokkal és a szponzorációkkal együtt hozzájárulnak a finanszírozásához. A BookStack tehát a saját szerverére települ, licenc vásárlása nélkül.

A BookStack követelményei

A Docker elhagyható marad. A projekt nem ad ki hivatalos image-et: a konténeres telepítések közösségi projektekből származnak, a LinuxServer.io-tól és a solidnerdtől. Ez az útmutató a hivatalos utat követi, a PHP-t és a MySQL-t közvetlenül a szerveren, amihez nem kell más.

A dokumentáció elveti a megosztott PHP-tárhelyet: a BookStack egy Ön által adminisztrált szervert igényel. Sem a szükséges memóriát, sem a processzort nem adja meg. Egy Managed VPS esetén írja le nekünk a használatát, a felhasználók számát, a képek és a csatolmányok mennyiségét, és mi azt a méretet javasoljuk, amely megfelel.

A BookStack telepítése

A projekt két utat kínál: egy Ubuntu-szkriptet, amely egy új szerveren a legrövidebb, és kézi telepítést minden más esetre.

A projekt szkriptjével, egy teljesen új Ubuntun

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

Ezek a szkriptek frissen telepített rendszerre valók: felülírhatnak egy meglévő webes konfigurációt. Két témát is érintetlenül hagynak, az e-mail-beállításokat és a rendszer biztonságát, amelyeket külön kell megoldani.

A szkript a BookStacket a /var/www/bookstack mappába teszi. Az Ubuntu 26.04-é bekéri a domaint és az adminisztrátori fiók címét, majd a végén kiír egy véletlenszerűen generált jelszót, amely nem szerepel a naplójában: jegyezze fel. Másik szkript esetén olvassa le a végén kiírt hozzáféréseket, és az első bejelentkezéskor módosítsa az alapértelmezett hozzáféréseket.

Kézzel, bármely más gépen

Kezdje az adatbázissal: egy adatbázis és egy erre az adatbázisra korlátozott felhasználó. A projekt szkriptje így jár el, a change-me helyén az Ön által választott jelszóval:

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;"

Ezután töltse le a release ágat, állítsa be a dokumentáció által a /var/www/bookstack mappához megadott jogokat, majd telepítse a függőségeket:

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

Adja meg az adatbázist és a címet a .env fájlban:

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

Végül irányítsa a webgyökeret a public mappára: DocumentRoot az Apache-on, root az Nginxen. Apache nélkül, vagy ha a .htaccess fájlok le vannak tiltva, adja hozzá a címátíró szabályokat: a projekt példákat közöl az Apache-hoz és az Nginxhez.

A kézi telepítés az admin@admin.com fiókkal és a password jelszóval nyílik meg. Az első bejelentkezéskor módosítsa a címet és a jelszót.

HTTPS és APP_URL

A látogatók a 80-as és a 443-as porton érkeznek, a szerver domainnevén. Hozzon létre ehhez a névhez A és AAAA rekordokat, majd kérje a tanúsítványt: az Ubuntu 26.04 szkriptje az Apache-ot csak a 80-as porton állítja be, a telepítési oldal pedig a HTTPS-t Önre bízza. A Certbot telepíti a Let's Encrypt-tanúsítványt, igazítja az Apache-ot, és magától megújítja a tanúsítványt. Nginx esetén cserélje le az --apache kapcsolót --nginx-re.

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

Ezután állítsa át a címet HTTPS-re a .env fájlban. Az APP_URL értékének pontosan egyeznie kell a látogatás címével, az előtaggal együtt: az eltérés hiányzó stílusokban, túlméretes ikonokban és elromlott menükben látszik. Egy https előtagú cím magától bekapcsolja a biztonságos sütiket.

APP_URL=https://docs.example.com

Ha már vannak oldalak, a linkjeik a régi címet őrzik az adatbázisban. Mentse az adatbázist, majd futtassa a projekt parancsát:

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

A BookStack egy domain vagy aldomain gyökerében szolgálja ki magát, a dokumentáció pedig egy almappa alatti telepítést is leír, például az example.com/bookstack címen. Ha egy fordított proxy kerül az Apache elé, adja meg a címét az APP_PROXIES változóban: nélküle az audit napló és a sebességkorlátozás a proxy címét látja a látogatók címe helyett. A dokumentáció az APP_PROXIES="*" értéket a hibakeresésnek tartja fenn.

Hol élnek az adatai

Tartsa meg ugyanazt az APP_KEY értéket hosszú távon, és mentse el. A BookStack ezzel titkosít többek között a kétlépcsős hitelesítés titkos adatait: a módosítása tönkreteheti ezeket a funkciókat, a 26.09-es verziótól pedig az alkalmazás hibát ad, ha hiányzik.

A képek alapértelmezésként nyilvánosak

Az alapértelmezett tárolással a webszerver közvetlenül szolgálja ki a képeket, ami gyors, és bárki megnyithatja őket, aki ismeri a címüket. Belső dokumentációhoz a választás a STORAGE_TYPE értékében történik:

A nagy fájlokhoz három beállításnak kell egyeznie: a FILE_UPLOAD_SIZE_LIMIT a .env fájlban, a post_max_size és az upload_max_filesize a php.ini fájlban, és a client_max_body_size az Nginxen, amelynek alapértéke 1 MB.

Két beállítás egy élő dokumentációnál is számít: minden oldal alapértelmezésként 100 változatot őriz (REVISION_LIMIT), a lomtár pedig 30 napig tartja meg a törölt elemeket (RECYCLE_BIN_LIFETIME).

Az e-mailek: SMTP és várólista

A BookStack e-maileket küld a címek megerősítéséhez, az elfelejtett jelszavakhoz, a meghívókhoz és az értesítésekhez. Simafri VPS-ről a küldés egy hitelesített SMTP-továbbítón keresztül megy, a 587-es porton: egy meglévő levelezési fiók címével, vagy a Simafri Suite-tal.

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

Ellenőrizze az eredményt a „Settings”, „Maintenance” menüben, a „Send a Test Email” művelettel, amely megjeleníti a felmerült hibákat. Egy meghívás közbeni hiba a képernyőn jelenik meg, míg egy értesítési hiba az alkalmazás naplójában marad.

Küldés a háttérben

Alapértelmezésként a BookStack a kérés közben küldi az e-maileket és a webhookokat, ami lassíthatja az oldalakat. A háttérbe váltáshoz írja a QUEUE_CONNECTION=database sort a .env fájlba, és futtasson egy szolgáltatást, a dokumentáció által egy szkripttel telepített Ubuntu-hoz adott példa szerint:

[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

A BookStack-példány biztonságossá tétele

A biztonsági dokumentáció egy listát ad, amelyet a telepítéstől kezdve érdemes átvenni:

1. Módosítsa az első adminisztrátor címét és jelszavát.
2. Ellenőrizze, hogy a webszerver csak a public mappát szolgálja ki, különösen, ha a BookStack a /var/www alatt él.
3. Korlátozza az adatbázis felhasználóját a BookStack saját adatbázisára.
4. Adja meg az APP_URL értékét, hogy a rendszer által generált címeket ne lehessen manipulálni.
5. Nézze át a regisztráció és a nyilvános hozzáférés beállításait, majd a szerepköröket.

A kétlépcsős hitelesítés ezután szerepkörönként előírható. Iratkozzon fel a projekt biztonsági levelezőlistájára is, hogy megkapja a riasztásait. Az /status cím felügyeletre szolgál: 200-zal válaszol, ha minden rendben van, egyébként 400-as vagy annál nagyobb hibakóddal.

A PHP ugyanannyit számít, mint a BookStack. A projekt 2026. október 21-én riasztást tett közzé egy kritikus PHP-frissítésről, amelyet a 8.5.12, a 8.4.27, a 8.3.36 és a 8.2.35 javít. Az Ubuntu ezeket a javításokat saját csomagszámai alatt adja ki, például a 8.3.6-0ubuntu0.24.04.13 az Ubuntu 24.04-hez.

A tartalmaihoz hagyja bekapcsolva az alapértelmezett szűrést, és csak azokon a példányokon lazítsa, ahol kizárólag megbízható személyek írnak. Ha egy adminisztrátori fiók elvész, a php artisan bookstack:create-admin létrehoz egy másikat, a php artisan bookstack:reset-mfa pedig eltávolítja egy felhasználó kétlépcsős hitelesítését.

Mentések és frissítések

Egy teljes mentés az adatbázist és a példányára jellemző négy fájlhelyet foglalja magában. A tartalom-exportok másra valók: a dokumentáció pontosítja, hogy nem helyettesítik a mentést.

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

Az első sor egy szkripttel végzett telepítésre vonatkozik, ahol a MySQL root felhasználója sudón keresztül csatlakozik; máshol írja a mysqldump -u bookstack -p bookstack parancsot. Tárolja ezt a két fájlt külön, lehetőleg egy másik gépen. Az archívum tartalmazza a .env fájlt, tehát az APP_KEY értékét és a jelszavait: kezelje titokként.

Visszaállítás

Egy új gépen telepítse a BookStacket a php artisan migrate futtatása nélkül, ezt a lépést kommentelje ki a szkriptben, ha azt használja, majd állítsa vissza az adatbázist és a fájlokat, az eredeti APP_KEY megtartásával:

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

Ha a telepített verzió újabb a mentésnél, ezután futtassa a php artisan migrate parancsot. Állítsa vissza a webszerver írási jogait a visszaállított mappákon. Ha a cím megváltozott, javítsa az APP_URL értékét, és futtassa a bookstack:update-url parancsot.

Frissítés

Minden frissítés előtt mentse az adatbázist és a fájlokat, majd a BookStack mappájából:

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

Az Ubuntu 26.04 szkriptje Composer nélkül telepíti a BookStacket. A frissítések oldala ilyenkor, bétaként, a ./bookstack-system-cli download-vendor parancsot ajánlja a composer install --no-dev helyett. Ugyanez az eszköz tud menteni és visszaállítani, de a projekt még nem tartja késznek az éles használatra: próbálja ki, mielőtt rábízná magát.

A dokumentáció verziónkénti tudnivalók listáját vezeti, amelyet a célzott verzióhoz kell elolvasni. Néhány példa:

• 26.09-es verzió: az APP_KEY kötelezővé válik.
• 26.05-ös verzió: a storage/fonts mappának írhatónak kell maradnia a webszerver számára, különben a PDF-exportok meghiúsulhatnak.
• 26.03-as verzió: a frissítés után próbálja ki az e-mail-küldést.
• 25.11-es verzió: nagy adatbázis-változások, amelyek migrációja egy nagy példányon több percig is eltarthat.

A hibákat karbantartó verziók javítják, mint a 2026. november 11-i 26.09.3: egy piszkozat állapotú vagy lomtárba helyezett oldal képei és rajzai elérhetők és módosíthatók maradtak, és egy szerkesztő személyes piszkozata más személyek számára is láthatóvá válhatott.

Ki mit csinál egy Managed VPS-en

A saját üzemeltetés az alkalmazás mellett a szerver gondozását is megköveteli. Egy Managed VPS esetén csapataink átveszik a szervert, és proaktívan követik a példányát; a BookStack továbbra is az Ön szoftvere marad, a beállításaival és az adataival.

Ha inkább azt szeretné, hogy csapataink magában az alkalmazásban avatkozzanak be, ez a szolgáltatás óradíjban vagy átalánydíjban számlázódik, a beavatkozás előtt közölt árajánlattal.