BookStack majutamine Managed VPS-is: teie dokumentatsioon teie enda juures

Mida BookStack teeb

BookStack on dokumentatsiooniplatvorm, mis on mõeldud lihtsaks jäämiseks: selle README taotleb kohest kasutuselevõttu, lihtsate tekstitöötluse teadmistega. Teie meeskonnad kirjutavad seal oma juhendeid, dokumentatsiooni ja teadmusbaasi, brauseris, soovi korral mitmes keeles.

• Neli korrastustaset: riiulid koondavad raamatuid, raamatud kannavad peatükke ja lehti, peatükid on valikulised ning sisu elab lehtedel.
• Kaks redaktorit: vaikimisi visuaalne redaktor ja Markdowni redaktor otse-eelvaatega, millele lisanduvad diagrams.net-i skeemid.
• Otsing: ühes raamatus või kõigis raamatutes, peatükkides ja lehtedel.
• Õigused: rollid kogu süsteemi jaoks ning riiulile, raamatule, peatükile või lehele omased õigused.
• Sisselogimised: e-post ja parool, OpenID Connect, SAML 2.0, LDAP, rakenduse või varukoodidega kaksikautentimine, mida saab rolli kaupa nõuda.
• Jälgimine ja vahetus: iga lehe redaktsioonide ajalugu, REST-API ning eksport HTML-i, PDF-i, teksti, Markdowni või kaasaskantavasse ZIP-i.

Projekt seisab oma valikute taga: selle README täpsustab, et BookStacki ei ole kavandatud muudele kasutusotstarvetele laiendatava platvormina, ja see jääb dokumentatsioonile truuks. Selle PDF-renderdus käib dompdf-iga, ilma lisapaigalduseta, piiratud võimalustega; projekt dokumenteerib muid mootoreid muutujaga EXPORT_PDF_COMMAND.

Mida MIT-litsents lubab

BookStack avaldatakse MIT-litsentsi all, Dan Browni ja projekti kaastööliste poolt. See lubab igasugust kasutust, muutmist ja levitamist ühe tingimusega: säilitada tarkvara igas koopias autoriõiguse teade ja litsentsi tekst. Projekti KKK täpsustab, et see viitamine puudutab koodi, mida jagate: miski ei kohusta teid oma instantsil BookStacki nime või logo kuvama.

Projekt hoiab ühte versiooni, vaba ja tasuta: see ei paku ettevõtteväljaannet ning sellel ei ole ametlikku majutust ega plaani seda avada. Seevastu müüb see tugipakette, mis aitavad koos annetuste ja sponsorlusega seda rahastada. BookStack paigaldatakse seega teie serverisse, ilma litsentsi ostmata.

BookStacki eeldused

Docker jääb valikuliseks. Projekt ei avalda ametlikku tõmmist: konteineripõhised paigaldused pärinevad kogukonna projektidest, LinuxServer.io ja solidnerd. See juhend järgib ametlikku teed, PHP ja MySQL otse serveris, mis ei nõua midagi lisaks.

Dokumentatsioon välistab jagatud PHP-majutuse: BookStack nõuab serverit, mida te haldate. See ei too välja ei vajalikku mälu ega protsessorit. Managed VPS-is kirjeldage meile oma kasutust, inimeste arvu ning piltide ja manuste mahtu ning soovitame sobiva suuruse.

BookStacki paigaldus

Projekt pakub kahte teed: skripti Ubuntu jaoks, uues serveris kõige lühemat, ja käsitsi paigaldust kõigil muudel juhtudel.

Projekti skriptiga, täiesti uues Ubuntus

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

Need skriptid on mõeldud värskelt paigaldatud süsteemile: need võivad olemasoleva veebiseadistuse üle kirjutada. Samuti jätavad need kõrvale kaks teemat, e-posti sätted ja süsteemi turvalisuse, mis tuleb ette näha eraldi.

Skript paigutab BookStacki kausta /var/www/bookstack. Ubuntu 26.04 oma küsib domeeni ja administraatorikonto aadressi ning kuvab lõpus juhusliku parooli, mida selle logis ei ole: märkige see üles. Teise skriptiga võtke lõpus kuvatud juurdepääsuandmed üles ja muutke igasugune vaikejuurdepääs esimesel sisselogimisel.

Käsitsi, mis tahes muus masinas

Alustage andmebaasist: üks andmebaas ja sellele andmebaasile piiratud kasutaja. Projekti skript toimib nii, teie valitud parooliga asemel 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;"

Tõmmake seejärel haru release, seadke õigused, mida dokumentatsioon kaustale /var/www/bookstack annab, ja paigaldage sõltuvused:

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

Sisestage andmebaas ja aadress faili .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

Suunake lõpuks veebijuur kaustale public: DocumentRoot Apache’is, root Nginxis. Ilma Apache’ita või kui failid .htaccess on keelatud, lisage aadressi ümberkirjutamise reeglid: projekt avaldab näited Apache’i ja Nginxi jaoks.

Käsitsi paigaldus avaneb kontoga admin@admin.com ja parooliga password. Muutke aadress ja parool esimesel sisselogimisel.

HTTPS ja APP_URL

Külastajad jõuavad portidele 80 ja 443, serveri domeeninime all. Looge sellele nimele A- ja AAAA-kirjed ning taotlege seejärel sertifikaat: Ubuntu 26.04 skript seadistab Apache’i ainult pordile 80 ja paigaldusleht jätab HTTPS-i teie hooleks. Certbot paigaldab Let’s Encrypti sertifikaadi, kohandab Apache’it ja uuendab sertifikaati ise. Nginxi puhul asendage --apache käsuga --nginx.

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

Seadke seejärel aadress failis .env HTTPS-ile. APP_URL peab täpselt vastama külastusaadressile, eesliide kaasa arvatud: lahknevus ilmneb puuduvate stiilide, ülisuurte ikoonide ja katkiste menüüde kaudu. Aadress kujul https lülitab turvaküpsised ise sisse.

APP_URL=https://docs.example.com

Kui lehti on juba olemas, jäävad nende lingid andmebaasis vana aadressi juurde. Varundage andmebaas ja käivitage seejärel projekti käsk:

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

BookStacki teenindatakse domeeni või alamdomeeni juurtasandil ja dokumentatsioon kirjeldab ka paigaldust alamkausta alla, näiteks example.com/bookstack. Kui Apache’i ette lisandub pöördproksi, deklareerige selle aadress muutujas APP_PROXIES: ilma selleta näevad auditilogi ja kiiruspiirang külastajate aadressi asemel proksi aadressi. Dokumentatsioon jätab APP_PROXIES="*" diagnostikaks.

Kus teie andmed elavad

Hoidke sama APP_KEY pikka aega ja varundage see. BookStack kasutab seda muu hulgas kaksikautentimise saladuste krüpteerimiseks: selle muutmine võib need funktsioonid rikkuda ning versioonist 26.09 alates annab rakendus tõrke, kui see puudub.

Pildid on vaikimisi avalikud

Vaikesalvestusega teenindab veebiserver pilte otse, mis on kiire, ja igaüks, kes nende aadressi teab, saab need avada. Sisedokumentatsiooni jaoks tehakse valik muutujas STORAGE_TYPE:

Suurte failide jaoks tuleb kolm sätet omavahel kooskõlla viia: FILE_UPLOAD_SIZE_LIMIT failis .env, post_max_size ja upload_max_filesize failis php.ini ning client_max_body_size Nginxis, mis on vaikimisi 1 MB.

Kaks sätet loevad ka elava dokumentatsiooni puhul: iga leht hoiab vaikimisi 100 redaktsiooni (REVISION_LIMIT) ja prügikast säilitab kustutatud elemente 30 päeva (RECYCLE_BIN_LIFETIME).

E-kirjad: SMTP ja järjekord

BookStack saadab e-kirju aadresside kinnitamiseks, unustatud parooli jaoks, kutseteks ja teavitusteks. Simafri VPS-ist läheb saatmine läbi autenditud SMTP-releesõlme pordis 587: selleks sobib teil juba olemasoleva e-postikonto aadress või 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

Kontrollige tulemust jaotises «Settings», «Maintenance», toiminguga «Send a Test Email», mis kuvab tekkinud tõrked. Kutsel ebaõnnestumine kuvatakse ekraanil, samas kui teavituse ebaõnnestumine jääb rakenduse logisse.

Taustal saatmine

Vaikimisi saadab BookStack e-kirjad ja webhookid päringu ajal, mis võib lehti aeglustada. Taustale üleminekuks kirjutage faili .env QUEUE_CONNECTION=database ja käitage teenust, dokumentatsiooni näitega Ubuntu skriptpaigalduse jaoks:

[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

BookStacki instantsi turvamine

Turvadokumentatsioon annab loendi, mida järgida juba paigaldusest alates:

1. Muutke esimese administraatori aadress ja parool.
2. Kontrollige, et veebiserver teenindab ainult kausta public, eriti kui BookStack elab kaustas /var/www.
3. Piirake andmebaasi kasutaja ainult BookStacki andmebaasiga.
4. Sisestage APP_URL, et süsteemi loodud aadresse ei saaks manipuleerida.
5. Vaadake üle registreerimise ja avaliku ligipääsu sätted ning seejärel rollid.

Kaksikautentimine nõutakse seejärel rolli kaupa. Tellige ka projekti turvalisuse meililist, et saada selle hoiatusi. Aadress /status sobib seireks: see vastab 200, kui kõik on korras, ja vastasel juhul veakoodiga, mis on 400 või suurem.

PHP loeb sama palju kui BookStack. Projekt avaldas 21. oktoobril 2026 hoiatuse PHP kriitilise uuenduse kohta, mis on parandatud versioonides 8.5.12, 8.4.27, 8.3.36 ja 8.2.35. Ubuntu avaldab need parandused oma pakettide numbrite all, näiteks 8.3.6-0ubuntu0.24.04.13 Ubuntu 24.04 jaoks.

Oma sisu jaoks hoidke vaikimisi lubatud filtreerimine ja jätke selle lõdvendamine instantsidele, kus kirjutavad ainult usaldusväärsed inimesed. Kui administraatorikonto kaob, loob php artisan bookstack:create-admin uue ja php artisan bookstack:reset-mfa eemaldab kasutaja kaksikautentimise.

Varukoopiad ja uuendused

Täielik varukoopia koondab andmebaasi ja teie instantsile omased neli failiasukohta. Sisueksportidel on teine ülesanne: dokumentatsioon täpsustab, et need ei asenda varukoopiat.

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

Esimene rida on mõeldud skriptpaigaldusele, kus MySQL-i root ühendub sudo kaudu; mujal kirjutage mysqldump -u bookstack -p bookstack. Hoidke need kaks faili eraldi, eelistatult teises masinas. Arhiiv sisaldab faili .env, seega APP_KEY-d ja teie paroole: käsitlege seda saladusena.

Taastamine

Uues masinas paigaldage BookStack ilma php artisan migrate käivitamata, samm, mis tuleb skriptis kommenteerida, kui seda kasutate, ja taastage seejärel andmebaas ja failid, hoides algset APP_KEY-d:

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

Kui paigaldatud versioon on varukoopiast uuem, käivitage seejärel php artisan migrate. Andke veebiserverile taastatud kaustadele tagasi kirjutusõigused. Kui aadress on muutunud, parandage APP_URL ja käivitage bookstack:update-url.

Uuendamine

Varundage enne iga uuendust andmebaas ja failid ning seejärel BookStacki kaustast:

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 skript paigaldab BookStacki ilma Composerita. Uuenduste leht pakub siis, beetana, ./bookstack-system-cli download-vendor käsu composer install --no-dev asemel. Sama tööriist oskab ka varundada ja taastada, kuid projekt ei pea seda veel tootmiseks valmis: testige seda enne, kui sellele loodate.

Dokumentatsioon peab loendit versioonikohastest juhistest, mida tuleb lugeda sihtversiooni jaoks. Mõned näited:

• Versioon 26.09: APP_KEY muutub kohustuslikuks.
• Versioon 26.05: kaust storage/fonts peab jääma veebiserverile kirjutatavaks, vastasel juhul võivad PDF-eksportid ebaõnnestuda.
• Versioon 26.03: proovige pärast uuendust e-kirjade saatmist.
• Versioon 25.11: suured andmebaasimuudatused, mille migratsioon võib suurel instantsil võtta mitu minutit.

Vead parandatakse hooldusversioonides, näiteks 26.09.3 11. novembrist 2026: mustandis või prügikastis oleva lehe pildid ja joonised jäid kättesaadavaks ja muudetavaks ning toimetaja isiklik mustand võis muutuda teistele inimestele nähtavaks.

Kes mida teeb Managed VPS-is

Ise majutamine nõuab lisaks rakendusele ka serveri hoidmist. Managed VPS-is võtavad meie meeskonnad serveri enda hoole alla ja jälgivad teie instantsi proaktiivselt; BookStack jääb teie tarkvaraks oma sätete ja andmetega.

Kui eelistate, et meie meeskonnad sekkuksid rakendusse endasse, arveldatakse see teenus tunni- või kindlahinnaga, hinnapakkumine edastatakse enne sekkumist.