Talpinkite BookStack Managed VPS serveryje: jūsų dokumentacija pas jus

Ką daro BookStack

BookStack yra dokumentacijos platforma, sukurta išlikti paprasta: jos README tikslas yra tuoj pat įsisavinti, pakanka paprastų tekstų redaktoriaus pagrindų. Jūsų komandos joje rašo savo procedūras, dokumentaciją ir žinių bazę, naršyklėje, lietuvių kalba, jei pageidauja.

• Keturi tvarkymo lygiai: lentynos grupuoja knygas, knygos turi skyrius ir puslapius, skyriai neprivalomi, o turinys gyvena puslapiuose.
• Du redaktoriai: numatytasis vizualinis redaktorius ir Markdown redaktorius su tiesiogine peržiūra, prie kurių prisideda diagrams.net schemos.
• Paieška: knygoje arba visose knygose, skyriuose ir puslapiuose.
• Teisės: vaidmenys visai sistemai ir leidimai, būdingi lentynai, knygai, skyriui ar puslapiui.
• Prisijungimai: el. paštas ir slaptažodis, OpenID Connect, SAML 2.0, LDAP, su dviejų veiksnių autentifikavimu per programą ar atsarginius kodus, kurį galima įpareigoti pagal vaidmenį.
• Sekimas ir mainai: kiekvieno puslapio redakcijų istorija, REST API ir eksportas HTML, PDF, tekstu, Markdown ar nešiojamu ZIP.

Projektas nuoširdžiai laikosi savo pasirinkimų: jo README nurodo, kad BookStack nėra sukurta kaip kitiems naudojimams išplečiama platforma, ir ji lieka ištikima dokumentacijai. Jos PDF generavimas vyksta per dompdf, be papildomo diegimo, su ribotomis galimybėmis; projektas aprašo kitus variklius su EXPORT_PDF_COMMAND.

Ką leidžia MIT licencija

BookStack platinama pagal MIT licenciją, kurią išleido Dan Brown ir projekto bendraautoriai. Ji leidžia bet kokį naudojimą, keitimą ir platinimą su viena sąlyga: kiekvienoje programinės įrangos kopijoje išsaugoti autorių teisių pranešimą ir licencijos tekstą. Projekto DUK nurodo, kad ši nuoroda taikoma jūsų dalijamam kodui: niekas neįpareigoja jūsų egzemplioriuje rodyti BookStack pavadinimo ar logotipo.

Projektas laiko vieną, laisvą ir nemokamą versiją: verslo leidimo jis nesiūlo ir neturi oficialaus talpinimo, nei ketinimo jį pradėti. Vietoje to parduoda palaikymo planus, kurie kartu su aukomis ir rėmimu prisideda prie jo finansavimo. Todėl BookStack diegiama jūsų serveryje, nieko nepirkus dėl licencijos.

BookStack reikalavimai

Docker lieka neprivalomas. Projektas neskelbia oficialaus atvaizdo: konteineriniai diegimai atsiranda iš bendruomenės projektų, LinuxServer.io ir solidnerd. Šis gidas seka oficialų kelią, PHP ir MySQL tiesiai serveryje, kuriam nieko daugiau nereikia.

Dokumentacija nepritaria bendrajam PHP talpinimui: BookStack reikalauja serverio, kurį administruojate. Ji nenurodo nei reikiamos atminties, nei procesoriaus. Naudojant Managed VPS, papasakokite mums, kaip ketinate naudotis, kiek bus žmonių ir kokia paveikslėlių bei priedų apimtis, ir mes rekomenduosime tinkamą dydį.

BookStack diegimas

Projektas siūlo du kelius: scenarijų Ubuntu, trumpiausią naujame serveryje, ir rankinį diegimą visais kitais atvejais.

Su projekto scenarijumi, visiškai naujame Ubuntu

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

Šie scenarijai skirti tik ką įdiegtai sistemai: jie gali perrašyti esamą žiniatinklio konfigūraciją. Jie taip pat palieka nuošalyje dvi temas, el. pašto nustatymus ir sistemos saugumą, kuriuos reikia numatyti atskirai.

Scenarijus BookStack įdeda į /var/www/bookstack. Ubuntu 26.04 scenarijus paprašo domeno ir administratoriaus paskyros adreso, o pabaigoje parodo atsitiktinai sugeneruotą slaptažodį, kurio jo žurnale nėra: užsirašykite jį. Su kitu scenarijumi pabaigoje parodytus prisijungimo duomenis užsirašykite, o bet kokią numatytąją prieigą pakeiskite jau pirmo prisijungimo metu.

Rankiniu būdu, bet kurioje kitoje mašinoje

Pradėkite nuo duomenų bazės: viena duomenų bazė ir naudotojas, apribotas šia duomenų baze. Projekto scenarijus daro taip, vietoj change-me įrašant pasirinktą slaptažodį:

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

Tada atsisiųskite šaką release, nustatykite dokumentacijos nurodytas teises katalogui /var/www/bookstack ir įdiekite priklausomybes:

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

Faile .env nurodykite duomenų bazę ir adresą:

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

Galiausiai nukreipkite žiniatinklio šaknį į katalogą public: DocumentRoot Apache, root Nginx. Be Apache arba kai failai .htaccess išjungti, pridėkite adresų perrašymo taisykles: projektas skelbia pavyzdžius Apache ir Nginx.

Rankinis diegimas atsidaro su paskyra admin@admin.com ir slaptažodžiu password. Adresą ir slaptažodį pakeiskite jau pirmo prisijungimo metu.

HTTPS ir APP_URL

Lankytojai atvyksta 80 ir 443 prievadais, serverio domeno vardu. Sukurkite šiam vardui A ir AAAA įrašus, tada paprašykite sertifikato: Ubuntu 26.04 scenarijus sukonfigūruoja Apache tik 80 prievadu, o diegimo puslapis HTTPS palieka jums. Certbot įdiegia Let's Encrypt sertifikatą, pritaiko Apache ir sertifikatą atnaujina pats. Su Nginx --apache pakeiskite į --nginx.

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

Tada faile .env adresą pakeiskite į HTTPS. APP_URL turi tiksliai atitikti lankymosi adresą, įskaitant priešdėlį: neatitikimas matomas pagal trūkstamus stilius, neproporcingas piktogramas ir sugedusius meniu. Adresas su https pats įjungia saugius slapukus.

APP_URL=https://docs.example.com

Jei puslapių jau yra, jų nuorodos duomenų bazėje išlaiko seną adresą. Sukurkite duomenų bazės atsarginę kopiją, tada paleiskite projekto komandą:

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

BookStack teikiama domeno ar subdomeno šaknyje, o dokumentacija aprašo ir diegimą poaplankyje, kaip example.com/bookstack. Jei prieš Apache pridedamas atvirkštinis tarpinis serveris, nurodykite jo adresą APP_PROXIES: be jo audito žurnalas ir spartos ribojimas mato tarpinio serverio adresą, o ne lankytojų. Dokumentacija APP_PROXIES="*" palieka diagnostikai.

Kur gyvena jūsų duomenys

Laikykite tą patį APP_KEY ilgam laikui ir sukurkite jo kopiją. BookStack jį naudoja, be kita ko, dviejų veiksnių autentifikavimo paslaptims šifruoti: pakeitus jį šios funkcijos gali sugesti, o nuo 26.09 versijos programa grąžina klaidą, jei jo nėra.

Paveikslėliai numatytai vieši

Su numatytąja saugykla žiniatinklio serveris paveikslėlius aptarnauja tiesiogiai, tai greita, ir kiekvienas, žinantis jų adresą, gali juos atidaryti. Vidinei dokumentacijai pasirinkimas daromas per STORAGE_TYPE:

Dideliems failams derinami trys nustatymai: FILE_UPLOAD_SIZE_LIMIT faile .env, post_max_size ir upload_max_filesize faile php.ini bei client_max_body_size Nginx, kuris numatytai yra 1 MB.

Gyvai dokumentacijai svarbūs ir du nustatymai: kiekvienas puslapis numatytai saugo 100 redakcijų (REVISION_LIMIT), o šiukšlinė ištrintus elementus saugo 30 dienų (RECYCLE_BIN_LIFETIME).

El. laiškai: SMTP ir eilė

BookStack siunčia el. laiškus adresų patvirtinimui, užmiršto slaptažodžio atveju, kvietimams ir pranešimams. Iš Simafri VPS siuntimas vyksta per autentifikuotą SMTP persiuntimo serverį 587 prievadu: tai gali būti jau turimos pašto paskyros adresas arba 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

Patikrinkite rezultatą skiltyse „Settings“, „Maintenance“, su veiksmu „Send a Test Email“, kuris parodo kilusias klaidas. Nepavykus išsiųsti kvietimo, klaida rodoma ekrane, o pranešimo nesėkmė lieka programos žurnale.

Siuntimas fone

Numatytai BookStack el. laiškus ir webhooks siunčia užklausos metu, o tai gali sulėtinti puslapius. Norėdami pereiti prie siuntimo fone, faile .env įrašykite QUEUE_CONNECTION=database ir paleiskite paslaugą pagal dokumentacijos pavyzdį Ubuntu diegimui su scenarijumi:

[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

BookStack egzemplioriaus apsauga

Saugumo dokumentacija pateikia sąrašą, kurį verta atlikti jau diegimo metu:

1. Pakeiskite pirmojo administratoriaus adresą ir slaptažodį.
2. Patikrinkite, ar žiniatinklio serveris aptarnauja tik katalogą public, ypač jei BookStack yra po /var/www.
3. Apribokite duomenų bazės naudotoją tik BookStack duomenų baze.
4. Nurodykite APP_URL, kad sistemos generuojamų adresų nebūtų galima manipuliuoti.
5. Peržiūrėkite registracijos ir viešos prieigos nustatymus, tada vaidmenis.

Dviejų veiksnių autentifikavimas po to įpareigojamas pagal vaidmenį. Taip pat užsiprenumeruokite projekto saugumo pranešimų sąrašą, kad gautumėte jo įspėjimus. Adresas /status skirtas stebėsenai: viskam gerai esant jis atsako 200, o kitu atveju klaidos kodu, lygiu ar didesniu nei 400.

PHP svarbus tiek pat, kiek BookStack. Projektas 2026 m. spalio 21 d. paskelbė įspėjimą apie kritinį PHP atnaujinimą, ištaisytą 8.5.12, 8.4.27, 8.3.36 ir 8.2.35 versijose. Ubuntu šias pataisas skelbia savo paketų numeriais, kaip 8.3.6-0ubuntu0.24.04.13 Ubuntu 24.04.

Savo turiniui palikite numatytąją filtraciją ir jos sušvelninimą skirkite egzemplioriams, kuriuose rašo tik patikimi asmenys. Jei administratoriaus paskyra pamesta, php artisan bookstack:create-admin sukuria kitą, o php artisan bookstack:reset-mfa pašalina naudotojo dviejų veiksnių autentifikavimą.

Atsarginės kopijos ir atnaujinimai

Pilna atsarginė kopija apima duomenų bazę ir keturias jūsų egzemplioriui būdingas failų vietas. Turinio eksportai skirti kitam: dokumentacija nurodo, kad jie atsarginės kopijos nepakeičia.

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

Pirmoji eilutė skirta diegimui su scenarijumi, kur MySQL root jungiasi per sudo; kitur rašykite mysqldump -u bookstack -p bookstack. Šiuos du failus padėkite atskirai, geriausia kitoje mašinoje. Archyve yra .env, taigi APP_KEY ir jūsų slaptažodžiai: traktuokite jį kaip paslaptį.

Atkūrimas

Naujoje mašinoje įdiekite BookStack nepaleisdami php artisan migrate, žingsnį scenarijuje užkomentuokite, jei jį naudojate, tada atkurkite duomenų bazę ir failus, išlaikydami pradinį APP_KEY:

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

Jei įdiegta versija naujesnė už atsarginę kopiją, po to paleiskite php artisan migrate. Grąžinkite žiniatinklio serverio rašymo teises atkurtiems katalogams. Jei adresas pasikeitė, pataisykite APP_URL ir paleiskite bookstack:update-url.

Atnaujinimas

Prieš kiekvieną atnaujinimą sukurkite duomenų bazės ir failų atsarginę kopiją, tada, iš BookStack katalogo:

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

Ubuntu 26.04 scenarijus įdiegia BookStack be Composer. Atnaujinimų puslapis tuomet, beta būsenoje, vietoj composer install --no-dev siūlo ./bookstack-system-cli download-vendor. Šis pats įrankis moka kurti ir atkurti atsargines kopijas, tačiau projektas dar nelaiko jo paruošto gamybai: išbandykite jį prieš juo pasikliaudami.

Dokumentacija laiko kiekvienai versijai būdingų nurodymų sąrašą, kurį reikia perskaityti tikslinei versijai. Keli pavyzdžiai:

• 26.09 versija: APP_KEY tampa privalomas.
• 26.05 versija: katalogas storage/fonts turi likti žiniatinklio serveriui prieinamas rašymui, kitaip PDF eksportai gali nepavykti.
• 26.03 versija: po atnaujinimo išbandykite el. laiškų siuntimą.
• 25.11 versija: dideli duomenų bazės pakeitimai, kurių migracija dideliame egzemplioriuje gali užtrukti kelias minutes.

Spragos taisomos priežiūros versijose, kaip 26.09.3, išleista 2026 m. lapkričio 11 d.: juodraščiu esančio ar į šiukšlinę perkelto puslapio paveikslėliai ir brėžiniai liko pasiekiami ir keičiami, o redaktoriaus asmeninis juodraštis galėjo tapti matomas kitiems asmenims.

Kas ką daro Managed VPS serveryje

Talpinant savo serveryje, be programos reikia prižiūrėti ir patį serverį. Naudojant Managed VPS, mūsų komandos perima serverį ir proaktyviai stebi jūsų egzempliorių; BookStack lieka jūsų programa su savo nustatymais ir duomenimis.

Jei norite, kad mūsų komandos įsikištų į pačią programą, ši paslauga apmokestinama valandomis arba fiksuota kaina, o skaičiavimas pateikiamas prieš įsikišimą.