Gostovanje BookStack na Managed VPS: vaša dokumentacija pri vas doma

Kaj počne BookStack

BookStack je platforma za dokumentacijo, zasnovana tako, da ostane preprosta: njegov README cilja na takojšnjo uporabo, z osnovnim znanjem urejevalnika besedil. Vaše ekipe vanj v brskalniku pišejo svoje postopke, dokumentacijo in bazo znanja, po želji tudi v slovenščini.

• Štiri ravni urejanja: police združujejo knjige, knjige nosijo poglavja in strani, poglavja so neobvezna, vsebina pa živi v straneh.
• Dva urejevalnika: privzeti vizualni urejevalnik in urejevalnik Markdown s predogledom v živo, ki ju dopolnjujejo diagrami diagrams.net.
• Iskanje: znotraj knjige ali po vseh knjigah, poglavjih in straneh.
• Pravice: vloge za ves sistem ter dovoljenja, značilna za polico, knjigo, poglavje ali stran.
• Prijave: e-pošta in geslo, OpenID Connect, SAML 2.0, LDAP, z dvostopenjskim preverjanjem pristnosti prek aplikacije ali rezervnih kod, ki ga je mogoče uvesti po vlogah.
• Sledenje in izmenjave: zgodovina revizij vsake strani, API REST in izvoz v HTML, PDF, besedilo, Markdown ali prenosljiv ZIP.

Projekt svoje izbire stoji za: njegov README pojasnjuje, da BookStack ni zasnovan kot platforma, razširljiva za druge rabe, in ostaja zvest dokumentaciji. Njegov izris PDF poteka prek dompdf, brez dodatne namestitve, z omejenimi zmožnostmi; projekt dokumentira druge pogone z EXPORT_PDF_COMMAND.

Kaj dovoljuje licenca MIT

BookStack je objavljen pod licenco MIT, avtorja Dan Brown in sodelavci projekta. Dovoljuje vsako rabo, vsako spremembo in vsako razpečevanje, pod enim pogojem: v vsaki kopiji programa ostaneta navedba avtorskih pravic in besedilo licence. FAQ projekta pojasnjuje, da se ta navedba nanaša na kodo, ki jo delite: nič vas ne zavezuje, da bi na svoji instanci prikazali ime ali logotip programa BookStack.

Projekt vzdržuje eno samo, prosto in brezplačno različico: ne ponuja izdaje za podjetja in nima uradnega gostovanja ter ga tudi ne namerava odpreti. Prodaja pa pakete podpore, ki skupaj z donacijami in pokroviteljstvi prispevajo k njegovemu financiranju. BookStack se torej namesti na vaš strežnik, ne da bi morali kupiti licenco.

Zahteve programa BookStack

Docker ostaja neobvezen. Projekt ne objavlja uradne slike: namestitve v vsebnikih izvirajo iz skupnostnih projektov, LinuxServer.io in solidnerd. Ta vodnik sledi uradni poti, PHP in MySQL neposredno na strežniku, ki ne zahteva ničesar več.

Dokumentacija odsvetuje skupno (deljeno) PHP gostovanje: BookStack zahteva strežnik, ki ga upravljate sami. Ne navaja potrebnega pomnilnika in procesorja. Na Managed VPS nam opišite svojo rabo, število oseb ter obseg slik in priponk, mi pa vam priporočimo ustrezno velikost.

Namestitev programa BookStack

Projekt ponuja dve poti: skripto za Ubuntu, najkrajšo na novem strežniku, in ročno namestitev za vse druge primere.

S skripto projekta, na povsem novem Ubuntuju

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 skripte so rezervirane za sveže nameščen sistem: lahko prepišejo obstoječo spletno konfiguracijo. Izpuščajo tudi dve temi, nastavitve e-pošte in varnost sistema, ki ju je treba urediti ločeno.

Skripta postavi BookStack v /var/www/bookstack. Tista za Ubuntu 26.04 vpraša po domeni in naslovu skrbniškega računa, na koncu pa prikaže naključno ustvarjeno geslo, ki ga ni v njenem dnevniku: zapišite si ga. Pri drugi skripti si zapišite dostope, prikazane na koncu, in vsak privzeti dostop spremenite že ob prvi prijavi.

Ročno, na kateremkoli drugem stroju

Začnite s podatkovno zbirko: ena zbirka in uporabnik, omejen nanjo. Skripta projekta poteka tako, z geslom po vaši izbiri namesto 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;"

Nato prenesite vejo release, nastavite pravice, ki jih dokumentacija navaja za /var/www/bookstack, nato namestite odvisnosti:

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

V .env vpišite zbirko in naslov:

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

Nazadnje spletni koren usmerite na mapo public: DocumentRoot v Apacheju, root v Nginxu. Brez Apachea ali ko so datoteke .htaccess onemogočene, dodajte pravila za prepisovanje naslovov: projekt objavlja primere za Apache in za Nginx.

Ročna namestitev se odpre z računom admin@admin.com in geslom password. Naslov in geslo spremenite že ob prvi prijavi.

HTTPS in APP_URL

Obiskovalci prihajajo na vrata 80 in 443, pod imenom domene strežnika. Za to ime ustvarite zapisa A in AAAA, nato zahtevajte potrdilo: skripta za Ubuntu 26.04 konfigurira Apache samo na vratih 80, namestitvena stran pa HTTPS prepušča vam. Certbot namesti potrdilo Let’s Encrypt, prilagodi Apache in potrdilo obnavlja sam. V Nginxu --apache zamenjajte z --nginx.

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

Nato naslov v .env preklopite na HTTPS. APP_URL se mora natančno ujemati z naslovom obiska, vključno s predpono: neujemanje se pokaže z manjkajočimi slogi, neprimerno velikimi ikonami in pokvarjenimi meniji. Naslov v https sam vključi varne piškotke.

APP_URL=https://docs.example.com

Če strani že obstajajo, njihove povezave v zbirki ohranijo stari naslov. Varnostno kopirajte zbirko, nato zaženite ukaz projekta:

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

BookStack se streže v korenu domene ali poddomene, dokumentacija pa opisuje tudi namestitev v podmapi, kot je example.com/bookstack. Če pred Apache dodate obratni posredniški strežnik, njegov naslov deklarirajte v APP_PROXIES: brez tega revizijski dnevnik in omejevanje hitrosti namesto naslova obiskovalcev vidijo naslov posredniškega strežnika. Dokumentacija APP_PROXIES="*" rezervira za diagnostiko.

Kje živijo vaši podatki

Isti APP_KEY ohranite skozi čas in ga varnostno kopirajte. BookStack z njim med drugim šifrira skrivnosti dvostopenjskega preverjanja pristnosti: njegova sprememba lahko pokvari te funkcije, od različice 26.09 pa aplikacija vrne napako, če manjka.

Slike so privzeto javne

S privzeto shrambo spletni strežnik slike streže neposredno, kar je hitro, in vsakdo, ki pozna njihov naslov, jih lahko odpre. Za notranjo dokumentacijo se izbira opravi v STORAGE_TYPE:

Pri težkih datotekah se uskladijo tri nastavitve: FILE_UPLOAD_SIZE_LIMIT v .env, post_max_size in upload_max_filesize v php.ini ter client_max_body_size v Nginxu, ki ima privzeto vrednost 1 MB.

Dve nastavitvi štejeta tudi za živo dokumentacijo: vsaka stran privzeto hrani 100 revizij (REVISION_LIMIT), koš pa izbrisane elemente hrani 30 dni (RECYCLE_BIN_LIFETIME).

E-pošta: SMTP in čakalna vrsta

BookStack pošilja e-pošto za potrditev naslovov, pozabljeno geslo, vabila in obvestila. Z VPS Simafri pošiljanje poteka prek overjenega releja SMTP, na vratih 587: z naslovom poštnega računa, ki ga že imate, ali s 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

Rezultat preverite v „Settings“, „Maintenance“, z dejanjem „Send a Test Email“, ki prikaže naletele napake. Neuspeh pri vabilu se prikaže na zaslonu, medtem ko neuspeh obvestila ostane v dnevniku aplikacije.

Pošiljanje v ozadju

BookStack privzeto e-pošto in webhooke pošilja med zahtevo, kar lahko upočasni strani. Za prehod v ozadje v .env zapišite QUEUE_CONNECTION=database in poganjajte storitev, s primerom, ki ga dokumentacija navaja za namestitev Ubuntu s skripto:

[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

Zavarovanje vaše instance BookStack

Varnostna dokumentacija navaja seznam, ki ga je treba uveljaviti že ob namestitvi:

1. Spremenite naslov in geslo prvega skrbnika.
2. Preverite, da spletni strežnik streže samo mapo public, zlasti če BookStack živi pod /var/www.
3. Uporabnika zbirke omejite na zbirko programa BookStack.
4. Vpišite APP_URL, da naslovov, ki jih ustvari sistem, ni mogoče manipulirati.
5. Preglejte nastavitve registracije in javnega dostopa, nato vloge.

Dvostopenjsko preverjanje pristnosti nato uvedite po vlogah. Prijavite se tudi na varnostni poštni seznam projekta, da prejemate njegova opozorila. Naslov /status služi nadzoru: odgovori 200, kadar je vse v redu, sicer pa s kodo napake 400 ali višjo.

PHP šteje toliko kot BookStack. Projekt je 21. oktobra 2026 objavil opozorilo o kritični posodobitvi PHP, popravljeni v 8.5.12, 8.4.27, 8.3.36 in 8.2.35. Ubuntu te popravke objavlja pod lastnimi številkami paketov, na primer 8.3.6-0ubuntu0.24.04.13 za Ubuntu 24.04.

Za svoje vsebine ohranite privzeto vključeno filtriranje, njegovo sprostitev pa rezervirajte za instance, kjer pišejo le zaupanja vredne osebe. Če se skrbniški račun izgubi, php artisan bookstack:create-admin ustvari drugega, php artisan bookstack:reset-mfa pa uporabniku odstrani dvostopenjsko preverjanje pristnosti.

Varnostne kopije in posodobitve

Popolna varnostna kopija združuje zbirko in štiri mesta datotek, značilna za vašo instanco. Izvozi vsebine služijo nečemu drugemu: dokumentacija pojasnjuje, da varnostne kopije ne nadomeščajo.

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

Prva vrstica velja za namestitev s skripto, kjer se root v MySQL povezuje prek sudo; drugje zapišite mysqldump -u bookstack -p bookstack. Ti dve datoteki hranite ločeno, po možnosti na drugem stroju. Arhiv vsebuje .env, torej APP_KEY in vaša gesla: obravnavajte ga kot skrivnost.

Obnova

Na novem stroju namestite BookStack, ne da bi zagnali php artisan migrate, korak, ki ga v skripti zakomentirate, če jo uporabljate, nato obnovite zbirko in datoteke, pri čemer ohranite prvotni APP_KEY:

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

Če je nameščena različica novejša od varnostne kopije, nato zaženite php artisan migrate. Obnovljenim mapam vrnite pravice pisanja spletnega strežnika. Če se je naslov spremenil, popravite APP_URL in zaženite bookstack:update-url.

Posodabljanje

Pred vsako posodobitvijo varnostno kopirajte zbirko in datoteke, nato v mapi programa BookStack:

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

Skripta za Ubuntu 26.04 namesti BookStack brez Composerja. Stran s posodobitvami nato v beti ponuja ./bookstack-system-cli download-vendor namesto composer install --no-dev. Isto orodje zna tudi varnostno kopirati in obnavljati, vendar ga projekt še ne šteje za pripravljenega na produkcijo: preizkusite ga, preden se nanj zanesete.

Dokumentacija vodi seznam navodil, značilnih za posamezno različico, ki jih je treba prebrati za ciljno različico. Nekaj primerov:

• Različica 26.09: APP_KEY postane obvezen.
• Različica 26.05: mapa storage/fonts mora ostati zapisljiva za spletni strežnik, sicer izvozi PDF lahko spodletijo.
• Različica 26.03: po posodobitvi preizkusite pošiljanje e-pošte.
• Različica 25.11: velike spremembe zbirke, katerih migracija lahko na veliki instanci traja več minut.

Ranljivosti se popravljajo v vzdrževalnih različicah, kot je 26.09.3 z dne 11. novembra 2026: slike in risbe strani, ki je bila osnutek ali v košu, so ostale dostopne in jih je bilo mogoče spreminjati, osebni osnutek urednika pa je lahko postal viden drugim osebam.

Kdo kaj dela na Managed VPS

Samostojno gostovanje poleg aplikacije zahteva tudi vzdrževanje strežnika. Na Managed VPS naše ekipe prevzamejo strežnik in proaktivno spremljajo vašo instanco; BookStack ostaja vaša programska oprema, z vašimi nastavitvami in podatki.

Če želite, da naše ekipe posežejo v samo aplikacijo, se ta storitev zaračuna po urah ali pavšalno, z oceno stroškov, sporočeno pred posegom.