Hostati BookStack na Managed VPS-u: vaša dokumentacija kod vas

Što radi BookStack

BookStack je platforma za dokumentaciju osmišljena da ostane jednostavna: njegov README cilja na trenutačno snalaženje, uz osnovno znanje obrade teksta. Vaši timovi u njemu, u pregledniku, pišu svoje postupke, dokumentaciju i bazu znanja, na hrvatskom ako žele.

• Četiri razine razvrstavanja: police okupljaju knjige, knjige nose poglavlja i stranice, poglavlja nisu obavezna, a sadržaj živi u stranicama.
• Dva uređivača: zadani vizualni uređivač i Markdown uređivač s pregledom uživo, kojima se pridodaju sheme iz diagrams.net.
• Pretraživanje: unutar knjige ili po svim knjigama, poglavljima i stranicama.
• Prava: uloge za cijeli sustav i dozvole svojstvene polici, knjizi, poglavlju ili stranici.
• Prijave: e-pošta i lozinka, OpenID Connect, SAML 2.0, LDAP, uz dvofaktorsku autentifikaciju aplikacijom ili pričuvnim kodovima, koja se može nametnuti po ulozi.
• Praćenje i razmjena: povijest revizija svake stranice, REST API i izvoz u HTML, PDF, tekst, Markdown ili prijenosni ZIP.

Projekt prihvaća svoje izbore: njegov README navodi da BookStack nije zamišljen kao platforma proširiva za druge namjene, i ostaje vjeran dokumentaciji. PDF prikaz ide preko dompdf-a, bez dodatne instalacije, s ograničenim mogućnostima; projekt dokumentira druge pogone s EXPORT_PDF_COMMAND.

Što dopušta licenca MIT

BookStack je objavljen pod licencom MIT od strane Dana Browna i suradnika projekta. Ona dopušta svaku upotrebu, izmjenu i distribuciju, uz jedan uvjet: napomena o autorskim pravima i tekst licence moraju ostati u svakoj kopiji softvera. FAQ projekta navodi da se ta atribucija odnosi na kod koji dijelite: ništa vas ne obvezuje da na svojoj instanci prikazujete naziv ili logotip BookStacka.

Projekt drži jednu, slobodnu i besplatnu inačicu: ne nudi poslovno izdanje i nema službeni hosting, niti plan da ga otvori. Prodaje, međutim, pakete podrške, koji uz donacije i pokroviteljstva pridonose njegovu financiranju. BookStack se stoga instalira na vaš poslužitelj, bez kupnje licence.

Preduvjeti BookStacka

Docker ostaje neobavezan. Projekt ne objavljuje službenu sliku: instalacije u kontejneru dolaze iz projekata zajednice, LinuxServer.io i solidnerd. Ovaj vodič prati službeni put, PHP i MySQL izravno na poslužitelju, koji ne traži ništa više.

Dokumentacija isključuje zajednički PHP hosting: BookStack traži poslužitelj kojim sami upravljate. Ne navodi potrebnu memoriju ni procesor. Na Managed VPS-u opišite nam svoju upotrebu, broj osoba te količinu slika i privitaka, a mi vam preporučujemo odgovarajuću veličinu.

Instalacija BookStacka

Projekt nudi dva puta: skriptu za Ubuntu, najkraću na novom poslužitelju, i ručnu instalaciju za sve ostale slučajeve.

Sa skriptom projekta, na sasvim novom Ubuntuu

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 su skripte rezervirane za svježe instaliran sustav: mogu prebrisati postojeću web-konfiguraciju. Izostavljaju i dvije teme, postavke e-pošte i sigurnost sustava, koje treba predvidjeti zasebno.

Skripta postavlja BookStack u /var/www/bookstack. Ona za Ubuntu 26.04 traži domenu i adresu administratorskog računa, a na kraju prikazuje nasumično generiranu lozinku, koje nema u njezinu zapisniku: zapišite je. S drugom skriptom pročitajte pristupne podatke prikazane na kraju i promijenite svaki zadani pristup već pri prvoj prijavi.

Ručno, na bilo kojem drugom stroju

Počnite s bazom podataka: jedna baza i korisnik ograničen na tu bazu. Skripta projekta postupa tako, s lozinkom po vašem izboru umjesto 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;"

Zatim preuzmite granu release, postavite prava koja dokumentacija daje za /var/www/bookstack i instalirajte ovisnosti:

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

U .env upišite bazu i 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

Naposljetku usmjerite web-korijen na mapu public: DocumentRoot na Apacheu, root na Nginxu. Bez Apachea, ili kad su datoteke .htaccess isključene, dodajte pravila za prepisivanje adresa: projekt objavljuje primjere za Apache i za Nginx.

Ručna instalacija otvara se s računom admin@admin.com i lozinkom password. Promijenite adresu i lozinku već pri prvoj prijavi.

HTTPS i APP_URL

Posjetitelji stižu na portove 80 i 443, pod nazivom domene poslužitelja. Izradite A i AAAA zapise za taj naziv, a zatim zatražite certifikat: skripta za Ubuntu 26.04 konfigurira Apache samo na portu 80, a instalacijska stranica HTTPS prepušta vama. Certbot postavlja certifikat Let’s Encrypt, prilagođava Apache i sam obnavlja certifikat. Uz Nginx zamijenite --apache s --nginx.

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

Zatim u .env prebacite adresu na HTTPS. APP_URL mora točno odgovarati adresi posjeta, uključujući prefiks: odstupanje se vidi po nedostajućim stilovima, prevelikim ikonama i pokvarenim izbornicima. Adresa u obliku https sama uključuje sigurne kolačiće.

APP_URL=https://docs.example.com

Ako stranice već postoje, njihove poveznice u bazi zadržavaju staru adresu. Sigurnosno kopirajte bazu, a zatim pokrenite naredbu projekta:

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

BookStack se poslužuje u korijenu domene ili poddomene, a dokumentacija opisuje i instalaciju u podmapi, poput example.com/bookstack. Ako se ispred Apachea doda obrnuti proxy, deklarirajte njegovu adresu u APP_PROXIES: bez toga revizijski zapisnik i ograničavanje brzine vide adresu proxyja umjesto adrese posjetitelja. Dokumentacija APP_PROXIES="*" rezervira za dijagnostiku.

Gdje žive vaši podaci

Dugoročno zadržite isti APP_KEY i sigurnosno ga kopirajte. BookStack ga koristi za šifriranje, među ostalim, tajni dvofaktorske autentifikacije: njegova promjena može pokvariti te funkcije, a od inačice 26.09 aplikacija vraća pogrešku ako nedostaje.

Slike su prema zadanim postavkama javne

Uz zadanu pohranu web-poslužitelj izravno poslužuje slike, što je brzo, a svatko tko zna njihovu adresu može ih otvoriti. Za internu dokumentaciju izbor se obavlja u STORAGE_TYPE:

Za velike datoteke usklađuju se tri postavke: FILE_UPLOAD_SIZE_LIMIT u .env, post_max_size i upload_max_filesize u php.ini te client_max_body_size na Nginxu, koji prema zadanim postavkama iznosi 1 MB.

Dvije postavke važne su i za živu dokumentaciju: svaka stranica prema zadanim postavkama čuva 100 revizija (REVISION_LIMIT), a koš čuva izbrisane elemente 30 dana (RECYCLE_BIN_LIFETIME).

E-pošta: SMTP i red čekanja

BookStack šalje e-poštu za potvrdu adresa, zaboravljenu lozinku, pozivnice i obavijesti. S Simafri VPS-a slanje ide preko autentificiranog SMTP releja, na portu 587: adresa računa e-pošte koji već imate ili 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

Provjerite rezultat u „Settings”, „Maintenance”, akcijom „Send a Test Email”, koja prikazuje nastale pogreške. Neuspjeh pri pozivnici prikazuje se na zaslonu, dok neuspjeh obavijesti ostaje u zapisniku aplikacije.

Slanje u pozadini

Prema zadanim postavkama BookStack šalje e-poštu i webhookove tijekom zahtjeva, što može usporiti stranice. Za prelazak u pozadinu upišite QUEUE_CONNECTION=database u .env i pokrenite uslugu, s primjerom koji dokumentacija daje za instalaciju na Ubuntuu putem skripte:

[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

Osiguravanje vaše instance BookStacka

Dokumentacija o sigurnosti daje popis koji treba preuzeti već pri instalaciji:

1. Promijenite adresu i lozinku prvog administratora.
2. Provjerite poslužuje li web-poslužitelj samo mapu public, osobito ako BookStack živi pod /var/www.
3. Ograničite korisnika baze samo na bazu BookStacka.
4. Upišite APP_URL, kako se adresama koje generira sustav ne bi moglo manipulirati.
5. Pregledajte postavke registracije i javnog pristupa, a zatim uloge.

Dvofaktorska autentifikacija zatim se nameće po ulozi. Pretplatite se i na sigurnosnu mailing listu projekta, kako biste primali njegova upozorenja. Adresa /status služi za nadzor: odgovara 200 kada sve ide dobro, a inače kodom pogreške jednakim ili većim od 400.

PHP vrijedi koliko i BookStack. Projekt je 21. listopada 2026. objavio upozorenje o kritičnom ažuriranju PHP-a, ispravljenom u 8.5.12, 8.4.27, 8.3.36 i 8.2.35. Ubuntu te ispravke objavljuje pod vlastitim brojevima paketa, poput 8.3.6-0ubuntu0.24.04.13 za Ubuntu 24.04.

Za svoje sadržaje zadržite zadano uključeno filtriranje, a njegovo ublažavanje rezervirajte za instance u kojima pišu samo osobe od povjerenja. Ako se administratorski račun izgubi, php artisan bookstack:create-admin izrađuje drugi, a php artisan bookstack:reset-mfa korisniku uklanja dvofaktorsku autentifikaciju.

Sigurnosne kopije i ažuriranja

Potpuna sigurnosna kopija okuplja bazu i četiri lokacije datoteka svojstvene vašoj instanci. Izvozi sadržaja služe nečem drugom: dokumentacija navodi da ne zamjenjuju sigurnosnu kopiju.

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

Prvi redak odnosi se na instalaciju putem skripte, gdje se MySQL root povezuje preko sudo; drugdje napišite mysqldump -u bookstack -p bookstack. Ove dvije datoteke spremite zasebno, po mogućnosti na drugi stroj. Arhiva sadrži .env, dakle APP_KEY i vaše lozinke: tretirajte je kao tajnu.

Vraćanje

Na novom stroju instalirajte BookStack bez pokretanja php artisan migrate, koraka koji treba zakomentirati u skripti ako je koristite, a zatim vratite bazu i datoteke, zadržavajući izvorni APP_KEY:

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

Ako je instalirana inačica novija od sigurnosne kopije, zatim pokrenite php artisan migrate. Vratite web-poslužitelju prava pisanja na vraćene mape. Ako se adresa promijenila, ispravite APP_URL i pokrenite bookstack:update-url.

Ažuriranje

Sigurnosno kopirajte bazu i datoteke prije svakog ažuriranja, a zatim, iz mape BookStacka:

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 instalira BookStack bez Composera. Stranica ažuriranja tada, u beti, predlaže ./bookstack-system-cli download-vendor umjesto composer install --no-dev. Isti alat zna sigurnosno kopirati i vraćati, ali ga projekt još ne smatra spremnim za produkciju: testirajte ga prije nego što se na njega oslonite.

Dokumentacija drži popis uputa svojstvenih svakoj inačici, koje treba pročitati za ciljanu inačicu. Nekoliko primjera:

• Inačica 26.09: APP_KEY postaje obavezan.
• Inačica 26.05: mapa storage/fonts mora ostati dostupna web-poslužitelju za pisanje, inače PDF izvozi mogu ne uspjeti.
• Inačica 26.03: nakon ažuriranja isprobajte slanje e-pošte.
• Inačica 25.11: velike promjene baze, čija migracija na velikoj instanci može potrajati nekoliko minuta.

Ranjivosti se ispravljaju u inačicama za održavanje, poput 26.09.3 od 11. studenoga 2026.: slike i crteži stranice u skici ili u košu za smeće ostajali su dostupni i mogli su se mijenjati, a osobna skica urednika mogla je postati vidljiva drugim osobama.

Tko što radi na Managed VPS-u

Hostanje na vlastitom poslužitelju traži da uz aplikaciju održavate i poslužitelj. Na Managed VPS-u naši timovi preuzimaju poslužitelj i proaktivno prate vašu instancu; BookStack ostaje vaš softver, sa svojim postavkama i podacima.

Ako želite da naši timovi interveniraju u samoj aplikaciji, ta se usluga naplaćuje po satu ili paušalno, uz procjenu koja vam se priopćuje prije intervencije.