BookStack cu Docker Compose: wiki pentru echipa pe VPS-ul tau

Orice echipa are acel om care stie cum merge scriptul de backup, la ce provider e domeniul si care e parola de la Wi-Fi-ul din birou. Totul merge bine pana cand omul respectiv pleaca in concediu, isi schimba jobul sau pur si simplu uita. Solutia e plictisitoare si incredibil de eficienta: scrii lucrurile undeva unde toata lumea poate cauta. In tutorialul asta construim exact acel loc, un wiki curat si rapid pe propriul VPS, cu BookStack, MariaDB si Docker Compose, cu HTTPS si email functional, ca colegii sa-si poata reseta singuri parolele fara sa te sune la 11 noaptea.

BookStack e o platforma open source de documentatie creata de Dan Brown, lansata sub licenta MIT. Site-ul oficial e bookstackapp.com , iar codul e pe github.com/BookStackApp/BookStack . E scris in PHP, pe framework-ul Laravel, si isi tine datele in MySQL sau MariaDB. La finalul ghidului il vei avea pornit, vei intelege cum isi organizeaza continutul, vei sti cum sa dai fiecarui om nivelul potrivit de acces si vei avea SMTP configurat pentru resetari de parola si invitatii.

Ce este BookStack si de ce se potriveste echipelor mici

Un wiki e un site in care un grup de oameni scriu si editeaza pagini impreuna, cu legaturi intre pagini, cu istoric pentru fiecare modificare si cu o casuta de cautare. Wikipedia e exemplul celebru, dar majoritatea wiki-urilor sunt mici si private: manualul intern al unei firme, procedurile unei echipe de dezvoltare, notitele de curs ale unui student sau documentatia homelab-ului unui pasionat.

Multe motoare de wiki iti dau o pagina alba si te lasa sa construiesti ce structura vrei. Suna bine si de obicei se termina in haos dupa sase luni. BookStack face invers: iti da o structura fixa si intuitiva, imprumutata de la o biblioteca, asa ca utilizatorii noi inteleg unde merg lucrurile fara niciun training. Peste asta primesti:

• Un editor WYSIWYG prietenos (ce vezi e ce obtii, ca intr-un procesor de text), plus un editor Markdown optional pentru cei care prefera textul simplu.
• Cautare full text in tot continutul, plus tag-uri dupa care poti filtra.
• Revizii: fiecare salvare se pastreaza, poti compara versiuni si restaura una mai veche din doua click-uri.
• Imagini, atasamente si diagrame, inclusiv un editor de diagrame draw.io integrat.
• Export in PDF, HTML, text simplu si Markdown, iar in versiunile recente si export ZIP pe care il poti importa in alta instanta BookStack.
• Roluri si permisiuni pana la nivel de pagina individuala.
• Autentificare multi-factor (aplicatii TOTP), plus LDAP, SAML2 si OpenID Connect daca ai deja un sistem central de login.
• Un API REST pentru automatizari.

De ce sa-l gazduiesti singur in loc de un wiki SaaS

Wiki-urile gazduite taxeaza per utilizator pe luna, iar factura creste cu fiecare angajare. Un BookStack self-hosted te costa un singur VPS mic, indiferent cate conturi creezi. In plus, documentatia ramane pe un server pe care il controlezi tu, intr-un data center din Romania, ceea ce simplifica mult discutiile despre GDPR cand wiki-ul contine proceduri pentru clienti sau date de contact interne.

Rafturi, carti, capitole si pagini: cum isi organizeaza BookStack continutul

Inainte sa instalam ceva, merita sa intelegem cele patru piese de baza, pentru ca ele influenteaza felul in care vei configura permisiunile mai tarziu.

• Pagina (page): documentul propriu-zis, unde scrii text, lipesti capturi de ecran si adaugi tabele. Tot restul exista ca sa organizeze paginile.
• Capitol (chapter): un grup optional de pagini in interiorul unei carti, ca un capitol dintr-un manual tiparit.
• Carte (book): containerul principal. O carte contine capitole si pagini, si de obicei la nivelul ei setezi permisiunile.
• Raft (shelf): o colectie de carti. Rafturile servesc doar la navigare si grupare, iar aceeasi carte poate sta pe mai multe rafturi in acelasi timp.

Iata cum si-ar putea structura o firma mica wiki-ul:

Raft: Tehnic
  Carte: Proceduri servere
    Capitol: Backup
      Pagina: Programul de backup zilnic
      Pagina: Restaurarea bazei MariaDB
    Capitol: Deployment
      Pagina: Checklist de lansare
  Carte: Onboarding programatori
    Pagina: Conturile de care ai nevoie
Raft: Birou
  Carte: HR si politici interne
    Pagina: Cereri de concediu

Doua reguli merita retinute. Prima, capitolele sunt optionale: o pagina poate sta direct intr-o carte, deci nu crea capitole doar de dragul lor. A doua, permisiunile curg in jos de la carte la capitolele si paginile ei, dar rafturile nu isi transmit automat permisiunile catre cartile de pe ele. Revenim la asta in sectiunea despre roluri.

De ce ai nevoie

• Un VPS DreamServer cu Debian 13 sau Ubuntu 24.04, minim 1 vCPU, 1 GB RAM si 10 GB disc (2 GB RAM e confortabil daca mai rulezi si alte lucruri).
• Un utilizator cu sudo si acces SSH la server.
• Un domeniu sau subdomeniu caruia ii poti edita DNS-ul, de exemplu wiki.firmata.ro.
• Un cont SMTP pentru trimis email: datele unei casute de mail pe domeniul tau sau ale unui serviciu de email tranzactional.
• Cam 30 de minute.

O nota despre virtualizare: pe un VPS KVM, tot ce urmeaza merge exact cum e scris. Intr-un container LXC neprivilegiat, Docker ruleaza doar daca e activat nesting-ul, iar unelte de firewall precum ufw s-ar putea sa nu-si poata incarca modulele de kernel. Daca esti pe unul dintre planurile noastre LXC si Docker refuza sa porneasca, cere suportului sa activeze nesting-ul sau alege KVM pentru workload-uri Docker.

Cum se leaga piesele intre ele

Sa definim cativa termeni. Un container e un pachet izolat care contine o aplicatie si tot ce ii trebuie ca sa ruleze, folosind kernelul gazdei, dar nu si fisierele sau procesele ei. O imagine e sablonul read-only din care pornesti un container. Un volum (aici, un folder de pe VPS montat in container) e locul unde stau datele care trebuie sa supravietuiasca restarturilor si actualizarilor. Un port e o usa numerotata a serverului prin care traficul de retea ajunge la un anumit program: 80 pentru HTTP, 443 pentru HTTPS, 3306 pentru MariaDB. Un reverse proxy e un server web care primeste toti vizitatorii pe porturile 80 si 443, se ocupa de certificatele HTTPS si trimite fiecare cerere catre aplicatia potrivita din spatele lui.

Stack-ul nostru are trei containere, descrise toate intr-un singur fisier docker-compose.yml. Docker Compose e unealta care citeste fisierul si porneste, opreste si actualizeaza containerele impreuna. Tot el creeaza o retea privata in care containerele se gasesc dupa numele serviciului, deci BookStack ajunge la baza de date simplu, la adresa db.

Despre imagini: proiectul BookStack nu publica o imagine Docker oficiala. Documentatia lui listeaza imagini comunitare, iar cea mai folosita e intretinuta de LinuxServer.io (lscr.io/linuxserver/bookstack), pe care o folosim si noi. Pentru baza de date folosim imaginea oficiala mariadb:11.4 (11.4 e o serie cu suport pe termen lung), iar pentru reverse proxy imaginea oficiala caddy:2, care obtine si reinnoieste automat certificate Let’s Encrypt.

Instalarea BookStack cu Docker Compose, pas cu pas

Toata instalarea are sapte pasi. Figura de mai jos iti da imaginea de ansamblu, iar fiecare sectiune numerotata care urmeaza corespunde unei casute.

Pasul 1: Instaleaza Docker pe Debian sau Ubuntu

Mai intai actualizam sistemul, apoi adaugam repository-ul oficial Docker, ca sa primim Docker Engine actual si plugin-ul Compose v2 (pachetele din distributie sunt deseori mai vechi).

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
. /etc/os-release
sudo curl -fsSL "https://download.docker.com/linux/${ID}/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Linia . /etc/os-release incarca doua variabile care descriu sistemul: ID este debian sau ubuntu, iar VERSION_CODENAME este trixie pe Debian 13 sau noble pe Ubuntu 24.04. De asta aceleasi comenzi merg pe ambele distributii: aleg automat repository-ul potrivit.

Daca upgrade-ul a instalat un kernel nou, da reboot. Pe Ubuntu poti verifica daca e nevoie de restart cu ls /var/run/reboot-required: daca fisierul exista, restarteaza. Debian nu creeaza acest fisier implicit, asa ca pe Debian pur si simplu da reboot dupa o actualizare de kernel.

Apoi permite utilizatorului tau sa ruleze Docker fara sudo de fiecare data, si delogheaza-te, ca schimbarea de grup sa intre in vigoare:

sudo usermod -aG docker $USER
exit

Dupa ce te reconectezi prin SSH, verifica instalarea:

docker --version
docker compose version
docker run --rm hello-world

Ar trebui sa vezi numerele de versiune pentru ambele unelte si mesajul “Hello from Docker!”. Retine ca apartenenta la grupul docker e echivalenta cu acces root, deci adauga acolo doar utilizatori de incredere.

La final, firewall-ul. Ubuntu vine cu ufw instalat, dar inactiv; pe Debian trebuie instalat intai. Permite intotdeauna SSH inainte sa-l activezi, altfel te blochezi singur afara:

sudo apt install -y ufw
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw enable
sudo ufw status

Un detaliu important pe care multi il rateaza: porturile publicate de Docker ocolesc ufw, pentru ca Docker isi scrie propriile reguli de firewall. Exact de asta designul nostru publica doar porturile 80 si 443 ale lui Caddy si nu publica niciodata portul 3306 al MariaDB sau portul intern al BookStack.

Pasul 2: Indreapta un domeniu catre VPS

Caddy are nevoie de un domeniu real ca sa obtina un certificat HTTPS. In panoul providerului de DNS, creeaza un record A pentru subdomeniul dorit, de exemplu wiki, care sa indice adresa IPv4 publica a VPS-ului. Daca VPS-ul are si IPv6, adauga un record AAAA cu acea adresa. Verifica de pe VPS ca numele se rezolva:

getent hosts wiki.firmata.ro

Rezultatul trebuie sa arate IP-ul serverului. Schimbarile DNS pot dura cateva minute; nu merge mai departe pana nu functioneaza, altfel Let’s Encrypt nu iti poate valida domeniul la Pasul 5.

Pasul 3: Creeaza folderul proiectului si secretele

Tinem totul intr-un singur folder: fisierul Compose, configuratia si datele. Valorile sensibile merg intr-un fisier .env, pe care Docker Compose il citeste automat si il inlocuieste in fisierul Compose oriunde vede ${VARIABILA}. Asa parolele nu stau in fisierul principal, iar backup-urile sunt simple.

mkdir -p ~/bookstack && cd ~/bookstack
cat > .env <<EOF
# Adresa publica a wiki-ului (fara https://, fara slash la final)
WIKI_DOMAIN=wiki.firmata.ro

# Cheia aplicatiei: generata o singura data, nu o mai schimba
APP_KEY=base64:$(openssl rand -base64 32)

# Parolele bazei de date (hex, deci fara caractere speciale)
DB_PASSWORD=$(openssl rand -hex 24)
DB_ROOT_PASSWORD=$(openssl rand -hex 24)

# Setari email, le completam la Pasul 7
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=wiki@firmata.ro
MAIL_PASSWORD=change-me
MAIL_FROM=wiki@firmata.ro
MAIL_FROM_NAME="Wiki echipa"
EOF
chmod 600 .env
cat .env

Bucatile $(openssl rand ...) se executa in momentul scrierii fisierului, deci cat .env ar trebui sa arate siruri lungi aleatoare, nu comenzile. chmod 600 face fisierul lizibil doar pentru utilizatorul tau. Acum deschide-l cu nano .env si inlocuieste wiki.firmata.ro cu domeniul tau real.

APP_KEY e cheia de criptare pe care Laravel o foloseste pentru sesiuni si alte date criptate. Trebuie sa inceapa cu base64: si trebuie sa ramana aceeasi pe toata durata instalarii: daca o schimbi ulterior, toata lumea e delogata si unele valori criptate devin ilizibile. Fa backup la .env impreuna cu datele.

Pasul 4: Scrie fisierul Docker Compose si Caddyfile

Creeaza docker-compose.yml cu nano docker-compose.yml si lipeste:

services:
  db:
    image: mariadb:11.4
    container_name: bookstack-db
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_DATABASE: bookstack
      MARIADB_USER: bookstack
      MARIADB_PASSWORD: ${DB_PASSWORD}
      TZ: Europe/Bucharest
    volumes:
      - ./db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s

  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: Europe/Bucharest
      APP_URL: https://${WIKI_DOMAIN}
      APP_KEY: ${APP_KEY}
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: bookstack
      DB_USERNAME: bookstack
      DB_PASSWORD: ${DB_PASSWORD}
      MAIL_DRIVER: smtp
      MAIL_HOST: ${MAIL_HOST}
      MAIL_PORT: ${MAIL_PORT}
      MAIL_ENCRYPTION: ${MAIL_ENCRYPTION}
      MAIL_USERNAME: ${MAIL_USERNAME}
      MAIL_PASSWORD: ${MAIL_PASSWORD}
      MAIL_FROM: ${MAIL_FROM}
      MAIL_FROM_NAME: ${MAIL_FROM_NAME}
    volumes:
      - ./config:/config

  caddy:
    image: caddy:2
    container_name: bookstack-caddy
    restart: unless-stopped
    depends_on:
      - bookstack
    environment:
      WIKI_DOMAIN: ${WIKI_DOMAIN}
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

Ce face fiecare parte:

• db: MariaDB tine paginile, utilizatorii si setarile. Variabilele MARIADB_* creeaza baza de date si un utilizator dedicat bookstack la primul start. healthcheck ii spune lui Docker cand baza de date e cu adevarat gata sa accepte conexiuni, nu doar pornita.
• bookstack: depends_on cu condition: service_healthy face ca BookStack sa astepte o baza de date sanatoasa, ceea ce evita erorile de conexiune la prima pornire. PUID si PGID sunt ID-urile de utilizator si grup care vor detine fisierele din ./config; verifica-le pe ale tale cu id -u si id -g si ajusteaza daca nu sunt 1000. APP_URL trebuie sa fie exact adresa publica, pentru ca BookStack construieste din ea fiecare link si redirect. Observa ca nu exista sectiune ports:: BookStack e accesibil doar prin Caddy.
• caddy: singurul serviciu cu porturi publicate. Certificatele lui stau in volumul caddy_data, deci supravietuiesc restarturilor si nu te lovesti de limitele Let’s Encrypt.

Despre tag-uri: mariadb:11.4 urmeaza versiunile de patch din seria LTS 11.4, ceea ce e sigur. Pentru BookStack folosim latest, care iti da mereu cea mai noua versiune la docker compose pull. BookStack lanseaza des si isi ruleaza automat migrarile de baza de date, deci e comod, dar inseamna si ca un update are loc de fiecare data cand dai pull. Daca preferi control total, inlocuieste latest cu un tag de versiune de forma version-vXX.YY.Z listat pe pagina imaginii si schimba-l constient, dupa ce citesti release notes.

Acum creeaza Caddyfile cu nano Caddyfile:

{$WIKI_DOMAIN} {
	encode zstd gzip
	reverse_proxy bookstack:80
}

{$WIKI_DOMAIN} se citeste din variabila de mediu pe care am dat-o containerului Caddy, deci domeniul e definit intr-un singur loc, fisierul .env. reverse_proxy bookstack:80 trimite fiecare cerere catre containerul BookStack prin reteaua privata Docker, iar encode comprima raspunsurile ca paginile sa se incarce mai repede.

Pasul 5: Porneste stack-ul

Din folderul ~/bookstack, porneste totul in fundal (-d inseamna detached):

cd ~/bookstack
docker compose up -d
docker compose ps

Docker descarca cele trei imagini, porneste MariaDB, asteapta pana raporteaza healthy, apoi porneste BookStack si Caddy. Dupa un minut, docker compose ps ar trebui sa arate bookstack-db cu starea Up (healthy) si pe celelalte doua Up. La primul start, BookStack isi creeaza tabelele, ceea ce poate dura 30-60 de secunde. Urmareste cu:

docker compose logs -f bookstack

Cand vezi o linie care se termina in [ls.io-init] done., aplicatia e gata. Apasa Ctrl+C ca sa nu mai urmaresti logurile (containerul ramane pornit). Poti verifica si ca Caddy a obtinut certificatul cu docker compose logs caddy, cautand mesajul care spune ca certificatul a fost obtinut cu succes.

Pasul 6: Prima logare si securizarea contului de admin

Deschide https://wiki.firmata.ro in browser. Ar trebui sa vezi lacatul valid si pagina de login BookStack. Datele implicite sunt:

• Email: admin@admin.com
• Parola: password

Schimba-le imediat, pentru ca le stie oricine a citit documentatia. Mergi la Settings (bara de sus), apoi Users, da click pe utilizatorul Admin, pune-ti numele si adresa de email reale, scrie o parola noua si puternica in campurile de parola si salveaza. Cat esti in profil, configureaza autentificarea multi-factor cu o aplicatie de autentificare si pastreaza codurile de backup intr-un loc sigur.

Apoi intra la Settings > Customization ca sa setezi numele aplicatiei (afisat in header si in emailuri), sa urci logo-ul si sa alegi culorile. Doua minute aici fac wiki-ul sa para unealta voastra, nu o instalare generica, iar asta ajuta adoptia mai mult decat ai crede.

Pasul 7: Configureaza emailul ca utilizatorii sa-si poata reseta parola

Fara email, o parola uitata inseamna un mesaj catre tine, iar invitatiile se trimit manual. Cu SMTP configurat, utilizatorii dau click pe “Forgot Password?” in pagina de login si primesc un link de resetare, iar tu poti invita colegi noi direct din pagina de utilizatori.

SMTP (Simple Mail Transfer Protocol) e modul standard prin care programele trimit email. Ai nevoie de patru lucruri de la providerul de mail: numele serverului, portul, un utilizator si o parola. Porturile conteaza:

• 587 e portul de submission cu STARTTLS (conexiunea porneste necriptata si e apoi trecuta pe criptare). E alegerea cea mai comuna.
• 465 foloseste TLS implicit (criptat de la primul byte). Merge si el.
• 25 e pentru livrare intre servere si e blocat la iesire de multi provideri si retele. Evita-l pentru scopul asta.

In BookStack, MAIL_ENCRYPTION=tls inseamna “cere criptare” si functioneaza atat cu portul 587, cat si cu 465. Foloseste null doar pentru un relay intern care nu suporta TLS. Editeaza sectiunea de mail din .env cu valorile tale reale:

nano ~/bookstack/.env

MAIL_HOST=mail.firmata.ro
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=wiki@firmata.ro
MAIL_PASSWORD=parola-casutei-de-mail
MAIL_FROM=wiki@firmata.ro
MAIL_FROM_NAME="Wiki echipa"

Aplica schimbarea. Compose observa ca s-a schimbat mediul lui BookStack si recreeaza doar acel container; datele raman neatinse, pentru ca stau in ./config si ./db:

cd ~/bookstack
docker compose up -d

Acum testeaza. Mergi la Settings > Maintenance si apasa Send a Test Email. BookStack trimite un mesaj la adresa contului tau si arata fie o confirmare, fie eroarea returnata de serverul SMTP. Apoi deschide o fereastra privata in browser, da click pe “Forgot Password?” in pagina de login, introdu emailul si verifica daca vine linkul de resetare.

Doua sfaturi practice. Foloseste un MAIL_FROM pe un domeniu pentru care providerul tau are voie sa trimita (inregistrari SPF si DKIM corecte), altfel mesajele ajung in spam sau sunt respinse. Iar daca vreodata variabilele par ignorate, imaginea pastreaza si fisierul de configurare BookStack in ./config/www/.env, unde poti seta aceleasi chei MAIL_*, urmat de docker compose restart bookstack.

Roluri si permisiuni in BookStack

Acum ca oamenii se pot loga si isi pot recupera conturile, e momentul sa decizi cine ce vede si ce modifica. Modelul BookStack are doua straturi.

Primul strat: rolurile

Un rol e un set de permisiuni cu nume, iar fiecare utilizator are unul sau mai multe roluri. O instalare noua are trei roluri obisnuite plus unul special:

Deschide Settings > Roles si da click pe un rol ca sa vezi doua sectiuni. System permissions controleaza abilitatile administrative: setarile aplicatiei, utilizatorii, rolurile, toate permisiunile de continut, exportul, schimbarea editorului de pagina si accesul la API. Asset permissions e o grila cu rafturi, carti, capitole, pagini, imagini, atasamente si comentarii pe o axa si creare, vizualizare, editare si stergere pe cealalta, unde fiecare celula poate fi “All” (tot) sau “Own” (doar ce a creat utilizatorul). De exemplu, un rol “Contributor” ar putea crea pagini, dar sa editeze si sa stearga doar paginile proprii, un compromis bun pentru o echipa mare.

Al doilea strat: permisiuni la nivel de continut

Orice raft, carte, capitol sau pagina are o actiune Permissions in bara laterala. Acolo poti suprascrie setarile rolurilor pentru acel element anume, de exemplu sa faci cartea “HR si politici interne” vizibila doar pentru Admin si pentru un rol nou “HR”, chiar daca in mod normal Editorii vad tot. Suprascrierile setate pe o carte se aplica tuturor capitolelor si paginilor ei, cu exceptia celor care au propriile setari.

Rafturile sunt exceptia: permisiunile lor controleaza cine vede raftul, nu cartile de pe el. Daca vrei ca si cartile sa preia aceleasi reguli, foloseste butonul Copy permissions to books din pagina de permisiuni a raftului.

Invitatii, acces public si inregistrare libera

• Invitatie: in Settings > Users > Add New User completezi numele, emailul si rolul si bifezi optiunea de trimitere a invitatiei pe email. Utilizatorul primeste un link ca sa-si aleaga singur parola, deci tu nu o vezi niciodata. Asta e primul castig adus de Pasul 7.
• Acces public: in Settings > Features & Security poti permite vizualizarea publica. Vizitatorii primesc atunci exact ce permite rolul Public. Excelent pentru documentatie publica de produs, periculos pentru un wiki intern, deci verifica de doua ori rolul Public inainte sa-l activezi.
• Inregistrare: in Settings > Registration poti lasa oamenii sa-si creeze singuri conturi, alegi rolul implicit, ceri confirmare pe email si restrictionezi inscrierile la domeniul firmei, de exemplu firmata.ro.

Backup si actualizari

Wiki-ul va deveni repede important, asa ca fa-i backup din prima zi. Doua lucruri trebuie salvate: baza de date si folderul ./config (imagini urcate, atasamente si configuratia BookStack), plus .env, fisierul Compose si Caddyfile.

cd ~/bookstack
docker compose exec -T db sh -c 'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" --single-transaction bookstack' > bookstack-db-$(date +%F).sql
sudo tar czf bookstack-files-$(date +%F).tar.gz config .env docker-compose.yml Caddyfile
ls -lh bookstack-*

Prima comanda ruleaza mariadb-dump in containerul bazei de date (unde parola de root e deja disponibila ca variabila de mediu) si scrie un fisier SQL consistent pe VPS. A doua arhiveaza fisierele. Copiaza-le pe amandoua in afara serverului, pentru ca un backup aflat pe acelasi disc nu supravietuieste pierderii discului. Ca sa restaurezi pe un server nou, recreezi folderul cu acelasi .env, dezarhivezi, pornesti doar baza de date cu docker compose up -d db, importi cu docker compose exec -T db sh -c 'mariadb -u root -p"$MARIADB_ROOT_PASSWORD" bookstack' < bookstack-db-DATA.sql, apoi rulezi docker compose up -d.

Actualizarea inseamna trei comenzi, dar fa intai un backup:

cd ~/bookstack
docker compose pull
docker compose up -d
docker image prune -f

pull descarca imaginile noi, up -d recreeaza containerele care s-au schimbat, iar BookStack isi aplica migrarile de baza de date la pornire. Daca vreodata muti MariaDB pe o serie majora noua (de exemplu de la 11.4 la un LTS viitor), fa backup inainte si adauga MARIADB_AUTO_UPGRADE: "1" in mediul serviciului db, ca fisierele de date sa fie actualizate automat.

Cat consuma de fapt?

BookStack e placut de usor. Pe un wiki de echipa mica, in repaus, cu cateva sute de pagini, cele trei containere folosesc impreuna cam o treime de gigabyte de RAM. Valorile de mai jos sunt aproximative si cresc cu traficul si continutul, dar arata de ce cele mai mici planuri VPS sunt suficiente.

Iti poti verifica oricand propriile valori cu docker stats --no-stream, care afiseaza consumul de CPU si memorie pentru fiecare container.

Depanare si greseli frecvente

• “502 Bad Gateway” imediat dupa pornire: BookStack inca isi ruleaza primele migrari. Asteapta un minut si urmareste docker compose logs -f bookstack pana vezi [ls.io-init] done.
• Fara certificat HTTPS, avertisment in browser: domeniul nu indica inca spre VPS sau portul 80 e blocat undeva. Verifica getent hosts domeniul-tau si docker compose logs caddy. Let’s Encrypt trebuie sa ajunga la server pe portul 80 sau 443 ca sa-l valideze.
• Stiluri stricate sau redirect catre adresa gresita: APP_URL nu se potriveste cu adresa din browser (http in loc de https, alt subdomeniu sau slash la final). Corecteaza WIKI_DOMAIN si ruleaza docker compose up -d. Daca schimbi domeniul unui wiki care are deja continut, actualizeaza si linkurile salvate in pagini cu docker compose exec bookstack php /app/www/artisan bookstack:update-url https://domeniu.vechi https://domeniu.nou.
• Erori de conexiune la baza de date dupa schimbarea parolei: MariaDB citeste variabilele MARIADB_* doar la primul start, cand ./db e gol. Daca schimbi ulterior DB_PASSWORD in .env, parola din baza de date nu se schimba. Fie revii la parola veche, fie actualizezi utilizatorul cu ALTER USER din containerul bazei de date.
• Emailul de test esueaza: citeste eroarea exacta din pagina Maintenance. “Connection timed out” inseamna de obicei port gresit sau blocat la iesire, “authentication failed” inseamna date de logare gresite, iar erorile de certificat inseamna ca numele de host nu se potriveste cu certificatul serverului. Pentru detalii, ruleaza docker compose logs bookstack si cauta logul aplicatiei cu sudo find ~/bookstack/config -name laravel.log.
• Te-ai blocat afara din contul de admin si emailul nu merge: creeaza un admin nou din linia de comanda cu docker compose exec bookstack php /app/www/artisan bookstack:create-admin --email=tu@firmata.ro --name=Tu --password=ParolaNouaPuternica. Daca un utilizator si-a pierdut dispozitivul MFA, aceeasi unealta ofera bookstack:reset-mfa.
• Erori “permission denied” in ./config: PUID si PGID nu corespund proprietarului folderului. Seteaza-le la rezultatul comenzilor id -u si id -g si recreeaza containerul.
• Docker nu porneste intr-un container LXC: nesting-ul nu e activat. Cere suportului sa-l activeze sau foloseste un VPS KVM.

Note de securitate

• Schimba imediat login-ul implicit si activeaza MFA pentru orice cont cu drepturi de admin. Din setarile fiecarui rol poti chiar sa faci MFA obligatoriu.
• Nu publica niciodata portul bazei de date. MariaDB trebuie sa fie accesibila doar in reteaua privata Docker, ca in fisierul nostru Compose. Nu uita ca porturile publicate de Docker ocolesc ufw.
• Protejeaza secretele: tine .env cu chmod 600, nu-l urca intr-un repository Git public si include-l in backup-urile criptate.
• Verifica rolul Public inainte sa activezi accesul public si restrictioneaza inregistrarea libera la domeniul tau daca o pornesti.
• Actualizeaza regulat si citeste release notes; BookStack publica rapid corecturile de securitate.
• Tine backup-urile in afara serverului si testeaza macar o data o restaurare, ca sa stii ca merge inainte sa ai nevoie de ea.
• Limiteaza SSH: foloseste autentificare cu chei, dezactiveaza login-ul cu parola si ia in calcul o unealta precum fail2ban.

Deci, e BookStack wiki-ul potrivit pentru tine?

Daca vrei documentatie pe care colegii fara background tehnic chiar o vor folosi, cu o structura care are sens din prima zi, permisiuni solide si resurse foarte modeste, BookStack e una dintre cele mai bune optiuni self-hosted. Cu setup-ul BookStack Docker Compose de mai sus ai un wiki securizat, cu HTTPS, care isi trimite singur emailurile de resetare a parolei si se actualizeaza din trei comenzi. Daca ai nevoie de ierarhii de pagini cu adancime nelimitata sau de un flux complet bazat pe Git, s-ar putea sa preferi alte unelte, dar pentru majoritatea echipelor modelul rafturi-carti-pagini e un avantaj, nu o limitare.

Poti porni acest stack pe un VPS de la noi in cateva minute, sau lasa echipa noastra de administrare servere sa-ti instaleze, securizeze, salveze si intretina wiki-ul BookStack.

Intrebari frecvente

Pot folosi BookStack gratuit si in scop comercial?

Da. BookStack e lansat sub licenta MIT, deci il poti folosi in orice scop, inclusiv intr-o firma, fara taxe de licenta. Singurul cost e serverul pe care ruleaza.

Cati utilizatori poate duce un VPS mic?

Un VPS de 1 GB serveste confortabil o echipa de cateva zeci de oameni care citesc si editeaza documentatie. Daca ai sute de utilizatori activi, exporturi PDF frecvente sau mii de imagini mari, treci pe 2 GB RAM sau mai mult.

Pot conecta BookStack la LDAP, Active Directory sau single sign-on?

Da. BookStack suporta LDAP, SAML2 si OpenID Connect, configurate prin variabile de mediu suplimentare. Utilizatorii se logheaza apoi cu conturile existente ale firmei, iar rolurile pot fi sincronizate din grupuri.

Pot rula BookStack fara domeniu?

Pentru un test rapid, da: publici portul BookStack (de exemplu "6875:80"), scoti Caddy si setezi APP_URL la http://ip-ul-tau:6875. Pentru folosire reala, foloseste mereu un domeniu cu HTTPS, altfel parolele circula necriptate.

Imi pot muta documentatia din BookStack mai tarziu?

Da. Orice carte, capitol sau pagina se poate exporta ca PDF, HTML, text simplu sau Markdown, versiunile recente adauga exporturi ZIP pe care le poate importa alta instanta BookStack, iar API-ul REST iti permite sa scriptezi migrari mai mari.