Găzduirea BookStack pe un Managed VPS: documentația pe propriul server

Ce face BookStack

BookStack este o platformă de documentație gândită să rămână simplă: README-ul său țintește o preluare imediată, cu simple noțiuni de procesare de text. Echipele dumneavoastră își scriu acolo procedurile, documentația și baza de cunoștințe, într-un browser, în română dacă doresc.

• Patru niveluri de organizare: rafturile grupează cărți, cărțile conțin capitole și pagini, capitolele sunt facultative, iar conținutul trăiește în pagini.
• Două editoare: un editor vizual implicit și un editor Markdown cu previzualizare în direct, cărora li se adaugă schemele diagrams.net.
• Căutarea: într-o carte sau în ansamblul cărților, capitolelor și paginilor.
• Drepturile: roluri pentru întregul sistem și permisiuni proprii unui raft, unei cărți, unui capitol sau unei pagini.
• Conectările: e-mail și parolă, OpenID Connect, SAML 2.0, LDAP, cu o autentificare în doi pași prin aplicație sau prin coduri de rezervă, care se poate impune pe rol.
• Urmărirea și schimburile: istoricul reviziilor fiecărei pagini, un API REST și exportul în HTML, PDF, text, Markdown sau ZIP portabil.

Proiectul își asumă alegerile: README-ul său precizează că BookStack nu este conceput ca o platformă extensibilă către alte utilizări și că rămâne ancorat în documentație. Randarea sa PDF trece prin dompdf, fără instalare în plus, cu capacități limitate; proiectul documentează alte motoare cu EXPORT_PDF_COMMAND.

Ce permite licența MIT

BookStack este publicat sub licența MIT de Dan Brown și de contributorii proiectului. Ea permite orice utilizare, orice modificare și orice distribuire, cu o singură condiție: păstrarea mențiunii de copyright și a textului licenței în orice copie a software-ului. FAQ-ul proiectului precizează că această atribuire privește codul pe care îl partajați: nimic nu vă obligă să afișați numele sau logoul BookStack pe instanța dumneavoastră.

Proiectul ține o singură versiune, liberă și gratuită: nu propune o ediție enterprise și nu are găzduire oficială, nici proiectul de a deschide una. În schimb, vinde formule de suport, care contribuie la finanțarea lui împreună cu donațiile și sponsorizările. BookStack se instalează deci pe serverul dumneavoastră, fără nicio licență de cumpărat.

Cerințele BookStack

Docker rămâne facultativ. Proiectul nu publică o imagine oficială: instalările în container provin din proiecte comunitare, LinuxServer.io și solidnerd. Acest ghid urmează calea oficială, PHP și MySQL direct pe server, care nu cere nimic în plus.

Documentația exclude găzduirea PHP partajată: BookStack cere un server pe care îl administrați. Ea nu indică nici memoria, nici procesorul necesare. Pe un Managed VPS, descrieți-ne utilizarea, numărul de persoane și volumul de imagini și de atașamente și vă recomandăm dimensiunea potrivită.

Instalarea BookStack

Proiectul propune două căi: un script pentru Ubuntu, cel mai scurt pe un server nou, și o instalare manuală pentru toate celelalte cazuri.

Cu scriptul proiectului, pe un Ubuntu proaspăt instalat

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

Aceste scripturi sunt rezervate unui sistem proaspăt instalat: ele pot suprascrie o configurație web existentă. Ele lasă deoparte și două subiecte, setările de e-mail și securitatea sistemului, de prevăzut separat.

Scriptul pune BookStack în /var/www/bookstack. Cel pentru Ubuntu 26.04 cere domeniul și adresa contului de administrator, apoi afișează la sfârșit o parolă generată aleatoriu, absentă din jurnalul său: notați-o. Cu un alt script, preluați accesele afișate la sfârșit și schimbați orice acces implicit de la prima conectare.

Manual, pe orice altă mașină

Începeți cu baza de date: o bază și un utilizator limitat la această bază. Scriptul proiectului procedează așa, cu parola aleasă de dumneavoastră în locul lui 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;"

Preluați apoi ramura release, setați drepturile pe care documentația le dă pentru /var/www/bookstack, apoi instalați dependențele:

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

Completați baza și adresa în .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

Indicați în sfârșit rădăcina web spre directorul public: DocumentRoot pe Apache, root pe Nginx. Fără Apache sau când fișierele .htaccess sunt dezactivate, adăugați regulile de rescriere a adreselor: proiectul publică exemple pentru Apache și pentru Nginx.

O instalare manuală se deschide cu contul admin@admin.com și parola password. Schimbați adresa și parola de la prima conectare.

HTTPS și APP_URL

Vizitatorii ajung pe porturile 80 și 443, sub numele de domeniu al serverului. Creați pentru acest nume înregistrări A și AAAA, apoi cereți certificatul: scriptul pentru Ubuntu 26.04 configurează Apache doar pe portul 80, iar pagina de instalare lasă HTTPS în seama dumneavoastră. Certbot instalează certificatul Let’s Encrypt, adaptează Apache și reînnoiește singur certificatul. Sub Nginx, înlocuiți --apache cu --nginx.

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

Treceți apoi adresa în HTTPS în .env. APP_URL trebuie să corespundă exact adresei de vizitare, prefix inclus: o diferență se vede prin stiluri lipsă, pictograme disproporționate și meniuri stricate. O adresă în https activează singură cookie-urile securizate.

APP_URL=https://docs.example.com

Dacă există deja pagini, linkurile lor păstrează vechea adresă în bază. Salvați baza, apoi rulați comanda proiectului:

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

BookStack se servește la rădăcina unui domeniu sau a unui subdomeniu, iar documentația descrie și o instalare sub un subdirector, precum example.com/bookstack. Dacă un proxy invers se adaugă în fața Apache, declarați adresa lui în APP_PROXIES: fără ea, jurnalul de audit și limitarea ratei văd adresa proxy-ului în locul celei a vizitatorilor. Documentația rezervă APP_PROXIES="*" diagnosticului.

Unde trăiesc datele dumneavoastră

Păstrați aceeași APP_KEY în timp și salvați-o. BookStack o folosește pentru a cripta, printre altele, secretele de autentificare în doi pași: schimbarea ei poate strica aceste funcții, iar începând cu versiunea 26.09 aplicația returnează o eroare dacă lipsește.

Imaginile sunt publice implicit

Cu stocarea implicită, serverul web servește direct imaginile, ceea ce merge repede, iar orice persoană care le cunoaște adresa le poate deschide. Pentru o documentație internă, alegerea se face în STORAGE_TYPE:

Pentru fișierele mari, trei setări trebuie să se potrivească: FILE_UPLOAD_SIZE_LIMIT în .env, post_max_size și upload_max_filesize în php.ini și client_max_body_size sub Nginx, care are implicit 1 MB.

Două setări contează și pentru o documentație vie: fiecare pagină păstrează implicit 100 de revizii (REVISION_LIMIT), iar coșul de gunoi păstrează elementele șterse 30 de zile (RECYCLE_BIN_LIFETIME).

E-mailurile: SMTP și coada de așteptare

BookStack trimite e-mailuri pentru confirmarea adreselor, parola uitată, invitații și notificări. De pe un VPS Simafri, trimiterea trece printr-un releu SMTP autentificat, pe portul 587: adresa unui cont de e-mail pe care îl aveți deja sau 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

Verificați rezultatul în „Settings”, „Maintenance”, cu acțiunea „Send a Test Email”, care afișează erorile întâlnite. Un eșec la o invitație se afișează pe ecran, în timp ce un eșec de notificare rămâne în jurnalul aplicației.

Trimiterea în fundal

Implicit, BookStack trimite e-mailurile și webhookurile în timpul cererii, ceea ce poate încetini paginile. Pentru a trece în fundal, scrieți QUEUE_CONNECTION=database în .env și rulați un serviciu, cu exemplul pe care documentația îl dă pentru o instalare Ubuntu prin script:

[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

Securizarea instanței BookStack

Documentația de securitate dă o listă de reluat încă de la instalare:

1. Schimbați adresa și parola primului administrator.
2. Verificați că serverul web servește doar directorul public, mai ales dacă BookStack se află sub /var/www.
3. Limitați utilizatorul bazei la baza BookStack.
4. Completați APP_URL, pentru ca adresele generate de sistem să nu poată fi manipulate.
5. Recitiți setările de înregistrare și de acces public, apoi rolurile.

Autentificarea în doi pași se impune apoi pe rol. Abonați-vă și la lista de difuzare de securitate a proiectului, pentru a-i primi alertele. Adresa /status servește unei monitorizări: ea răspunde 200 când totul merge bine și un cod de eroare egal sau mai mare de 400 în caz contrar.

PHP contează la fel de mult ca BookStack. Proiectul a publicat pe 21 octombrie 2026 o alertă privind o actualizare critică a PHP, corectată în 8.5.12, 8.4.27, 8.3.36 și 8.2.35. Ubuntu publică aceste corecturi sub propriile numere de pachete, precum 8.3.6-0ubuntu0.24.04.13 pentru Ubuntu 24.04.

Pentru conținutul dumneavoastră, păstrați activată filtrarea implicită și rezervați relaxarea ei instanțelor în care scriu doar persoane de încredere. Dacă un cont de administrator se pierde, php artisan bookstack:create-admin creează altul, iar php artisan bookstack:reset-mfa elimină autentificarea în doi pași a unui utilizator.

Backupuri și actualizări

Un backup complet reunește baza și cele patru locații de fișiere proprii instanței dumneavoastră. Exporturile de conținut servesc altui scop: documentația precizează că ele nu înlocuiesc un backup.

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

Prima linie vizează o instalare prin script, unde root MySQL se conectează prin sudo; în alte părți, scrieți mysqldump -u bookstack -p bookstack. Puneți aceste două fișiere deoparte, de preferat pe altă mașină. Arhiva conține .env, deci APP_KEY și parolele dumneavoastră: tratați-o ca pe un secret.

Restaurarea

Pe o mașină nouă, instalați BookStack fără a rula php artisan migrate, o etapă de comentat în script dacă îl folosiți, apoi restaurați baza și fișierele, păstrând APP_KEY de origine:

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

Dacă versiunea instalată este mai recentă decât backupul, rulați apoi php artisan migrate. Puneți la loc drepturile de scriere ale serverului web pe directoarele restaurate. Dacă adresa s-a schimbat, corectați APP_URL și rulați bookstack:update-url.

Actualizarea

Salvați baza și fișierele înaintea fiecărei actualizări, apoi, din directorul BookStack:

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

Scriptul pentru Ubuntu 26.04 instalează BookStack fără Composer. Pagina actualizărilor propune atunci, în beta, ./bookstack-system-cli download-vendor în locul lui composer install --no-dev. Același instrument știe să salveze și să restaureze, dar proiectul nu îl consideră încă pregătit pentru producție: testați-l înainte de a vă baza pe el.

Documentația ține o listă de indicații proprii fiecărei versiuni, de citit pentru versiunea vizată. Câteva exemple:

• Versiunea 26.09: APP_KEY devine obligatorie.
• Versiunea 26.05: directorul storage/fonts trebuie să rămână accesibil pentru scriere serverului web, altfel exporturile PDF pot eșua.
• Versiunea 26.03: încercați trimiterea e-mailurilor după actualizare.
• Versiunea 25.11: modificări mari ale bazei, a căror migrare poate dura mai multe minute pe o instanță mare.

Breșele se corectează în versiuni de mentenanță, precum 26.09.3 din 11 noiembrie 2026: imaginile și desenele unei pagini în ciornă sau în coșul de gunoi rămâneau accesibile și modificabile, iar ciorna personală a unui editor putea deveni vizibilă pentru alte persoane.

Cine ce face pe un Managed VPS

Găzduirea pe propriul server cere să țineți serverul pe lângă aplicație. Pe un Managed VPS, echipele noastre preiau serverul și vă urmăresc proactiv instanța; BookStack rămâne software-ul dumneavoastră, cu setările și datele sale.

Dacă preferați ca echipele noastre să intervină în aplicația însăși, această prestație se facturează la oră sau la preț fix, cu o ofertă comunicată înainte de intervenție.