Mitināt BookStack Managed VPS serverī: jūsu dokumentācija pie jums

Ko dara BookStack

BookStack ir dokumentācijas platforma, kas veidota, lai palīktu vienkārša: tās README mērķis ir tūlītēja apgūšana ar elementārām teksta apstrādes zināšanām. Jūsu komandas tajā raksta savas procedūras, savu dokumentāciju un savu zināšanu bāzi, pārlūkprogrammā, latviešu valodā, ja vēlas.

• Četri kārtošanas līmeņi: plaukti apvieno grāmatas, grāmatas satur nodaļas un lapas, nodaļas nav obligātas, un saturs dzīvo lapās.
• Divi redaktori: vizuālais redaktors pēc noklusējuma un Markdown redaktors ar tiešo priekšskatījumu, kam pievienojas diagrams.net shēmas.
• Meklēšana: grāmatā vai visās grāmatās, nodaļās un lapās.
• Tiesības: lomas visai sistēmai un atļaujas, kas raksturīgas plauktam, grāmatai, nodaļai vai lapai.
• Pieteikšanās: e-pasts un parole, OpenID Connect, SAML 2.0, LDAP, ar divfaktoru autentifikāciju ar lietotni vai rezerves kodiem, ko var uzlikt pēc lomas.
• Uzraudzība un apmaiņa: katras lapas pārskatījumu vēsture, REST API un eksports HTML, PDF, teksta, Markdown vai pārnēsājamā ZIP formātā.

Projekts uzņemas savas izvēles: tā README precizē, ka BookStack nav veidots kā platforma, ko paplašināt citiem lietojumiem, un tas paliek uzticīgs dokumentācijai. Tā PDF renderēšana iet caur dompdf, bez papildu uzstādīšanas, ar ierobežotām iespējām; projekts dokumentē citus dzinējus ar EXPORT_PDF_COMMAND.

Ko atļauj MIT licence

BookStack tiek izplatīts ar MIT licenci, ko izdevuši Dan Brown un projekta līdzstrādnieki. Tā atļauj jebkādu lietojumu, jebkādu mainīšanu un jebkādu izplatīšanu ar vienu nosacījumu: katrā programmatūras kopijā saglabāt autortiesību norādi un licences tekstu. Projekta BUJ precizē, ka šī atribūcija attiecas uz kodu, ko koplietojat: nekas jūs nepiespiež savā instancē rādīt BookStack nosaukumu vai logotipu.

Projekts uztur vienu versiju, brīvu un bezmaksas: tas nepiedāvā uzņēmumu izdevumu, tam nav oficiālas mitināšanas un nav nodoma to atvērt. Tas gan pārdod atbalsta plānus, kas līdzās ziedojumiem un sponsorēšanai palīdz to finansēt. BookStack tātad uzstādās uz jūsu servera, nepērkot nekādu licenci.

BookStack prasības

Docker paliek neobligāts. Projekts nepublicē oficiālu attēlu: konteineru instalācijas nāk no kopienas projektiem, LinuxServer.io un solidnerd. Šis ceļvedis seko oficiālajam ceļam, PHP un MySQL tieši serverī, kas neprasa neko vairāk.

Dokumentācija atsaka koplietojamo PHP mitināšanu: BookStack vajadzīgs serveris, ko pārvaldāt jūs. Tā nenosauc vajadzīgo atmiņu un procesoru. Ar Managed VPS aprakstiet mums savu lietojumu, cilvēku skaitu un attēlu un pielikumu apjomu, un mēs jums iesakām piemērotu izmēru.

BookStack uzstādīšana

Projekts piedāvā divus ceļus: skriptu Ubuntu videi, visīsāko uz jauna servera, un manuālu uzstādīšanu visiem pārējiem gadījumiem.

Ar projekta skriptu, uz pilnīgi jauna 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 skripti paredzēti tikko uzstādītai sistēmai: tie var pārrakstīt esošu tīmekļa konfigurāciju. Tie atstāj malā arī divas tēmas, e-pasta iestatījumus un sistēmas drošību, kas jāparedz atsevišķi.

Skripts novieto BookStack mapē /var/www/bookstack. Ubuntu 26.04 skripts pieprasa domēnu un administratora konta adresi, pēc tam beigās parāda nejauši iegūtu paroli, kas nav tā žurnālā: pierakstiet to. Ar citu skriptu izlasiet beigās parādītos piekļuves datus un nomainiet jebkuru noklusējuma piekļuvi jau pirmajā pieslēgšanās reizē.

Ar rokām, uz jebkuras citas mašīnas

Sāciet ar datubāzi: viena datubāze un lietotājs, kas ierobežots ar šo datubāzi. Projekta skripts rīkojas tā, ar jūsu izvēlēto paroli change-me vietā:

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

Pēc tam iegūstiet zaru release, iestatiet tiesības, ko dokumentācija dod mapei /var/www/bookstack, un uzstādiet atkarības:

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

Failā .env norādiet datubāzi un adresi:

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

Visbeidzot novirziet tīmekļa sakni uz mapi public: DocumentRoot Apache, root Nginx. Bez Apache vai tad, kad faili .htaccess ir atslēgti, pievienojiet adrešu pārrakstīšanas noteikumus: projekts publicē piemērus Apache un Nginx.

Manuāla instalācija atveras ar kontu admin@admin.com un paroli password. Nomainiet adresi un paroli jau pirmajā pieslēgšanās reizē.

HTTPS un APP_URL

Apmeklētāji nonāk uz portiem 80 un 443, ar servera domēna vārdu. Izveidojiet šim vārdam A un AAAA ierakstus, pēc tam pieprasiet sertifikātu: Ubuntu 26.04 skripts konfigurē Apache tikai uz porta 80, un instalēšanas lapa HTTPS atstāj jūsu ziņā. Certbot uzstāda Let's Encrypt sertifikātu, pielāgo Apache un sertifikātu atjauno pats. Ar Nginx aizstājiet --apache ar --nginx.

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

Pēc tam failā .env nomainiet adresi uz HTTPS. APP_URL jāatbilst apmeklējuma adresei precīzi, ar prefiksu: neatbilstība izpaužas kā trūkstoši stili, pārmērīgi lielas ikonas un salauztas izvēlnes. Adrese ar https pati ieslēdz drošos sīkfailus.

APP_URL=https://docs.example.com

Ja lapas jau pastāv, to saites datubāzē paturēs veco adresi. Izveidojiet datubāzes rezerves kopiju, pēc tam palaidiet projekta komandu:

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

BookStack tiek padarīts pieejams domēna vai apakšdomēna saknē, un dokumentācija apraksta arī instalāciju apakšmapē, piemēram, example.com/bookstack. Ja pirms Apache pievienojas reversais starpniekserveris, deklarējiet tā adresi mainīgajā APP_PROXIES: bez tās audita žurnāls un ātruma ierobežošana redz starpniekservera adresi apmeklētāju adreses vietā. Dokumentācija APP_PROXIES="*" rezervē diagnostikai.

Kur dzīvo jūsu dati

Paturiet to pašu APP_KEY ilgstoši un veidojiet tās rezerves kopiju. BookStack to izmanto, lai šifrētu, cita starpā, divfaktoru autentifikācijas noslēpumus: tās maiņa var salauzt šīs funkcijas, un kopš versijas 26.09 lietojumprogramma atgriež kļūdu, ja tās nav.

Attēli pēc noklusējuma ir publiski

Ar noklusējuma glabāšanu tīmekļa serveris attēlus apkalpo tieši, kas ir ātri, un ikviens, kas zina to adresi, var tos atvērt. Iekšējai dokumentācijai izvēle tiek veikta mainīgajā STORAGE_TYPE:

Smagiem failiem saskaņojas trīs iestatījumi: FILE_UPLOAD_SIZE_LIMIT failā .env, post_max_size un upload_max_filesize failā php.ini un client_max_body_size Nginx, kas pēc noklusējuma ir 1 MB.

Dzīvai dokumentācijai svarīgi arī divi iestatījumi: katra lapa pēc noklusējuma glabā 100 pārskatījumus (REVISION_LIMIT), un atkritne dzēstos elementus saglabā 30 dienas (RECYCLE_BIN_LIFETIME).

E-pasti: SMTP un rinda

BookStack sūta e-pastus adrešu apstiprināšanai, aizmirstai parolei, ielūgumiem un paziņojumiem. No Simafri VPS sūtīšana notiek caur autentificētu SMTP releju, izmantojot portu 587: ar jau esoša pasta konta adresi vai 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

Pārbaudiet rezultātu sadaļā «Settings», «Maintenance», ar darbību «Send a Test Email», kas parāda konstatētās kļūdas. Neveiksme ielūguma laikā tiek parādīta ekrānā, savukārt paziņojuma neveiksme paliek lietojumprogrammas žurnālā.

Sūtīšana fonā

Pēc noklusējuma BookStack e-pastus un webhooks sūta pieprasījuma laikā, kas var palēnināt lapas. Lai pārietu uz fonu, failā .env ierakstiet QUEUE_CONNECTION=database un darbiniet pakalpojumu, ar piemēru, ko dokumentācija dod Ubuntu instalācijai ar skriptu:

[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

Jūsu BookStack instances drošība

Drošības dokumentācija dod sarakstu, ko pārņemt jau instalēšanas brīdī:

1. Nomainiet pirmā administratora adresi un paroli.
2. Pārbaudiet, ka tīmekļa serveris apkalpo tikai mapi public, īpaši, ja BookStack atrodas zem /var/www.
3. Ierobežojiet datubāzes lietotāju ar vienīgo BookStack datubāzi.
4. Norādiet APP_URL, lai sistēmas ģenerētās adreses nevarētu manipulēt.
5. Pārlasiet reģistrācijas un publiskās piekļuves iestatījumus, pēc tam lomas.

Divfaktoru autentifikāciju pēc tam uzliek pēc lomas. Pierakstieties arī projekta drošības izplatīšanas sarakstā, lai saņemtu tā brīdinājumus. Adrese /status kalpo uzraudzībai: tā atbild 200, kad viss ir kārtībā, un citādi ar kļūdas kodu, kas vienāds ar 400 vai lielāks.

PHP skaitās tikpat, cik BookStack. Projekts 2026. gada 21. oktobrī publicēja brīdinājumu par kritisku PHP atjauninājumu, labotu versijās 8.5.12, 8.4.27, 8.3.36 un 8.2.35. Ubuntu šos labojumus publicē ar savu pakotņu numuriem, piemēram, 8.3.6-0ubuntu0.24.04.13 Ubuntu 24.04.

Savam saturam paturiet noklusējumā ieslēgto filtrēšanu un tās atslābināšanu rezervējiet instancēm, kur raksta tikai uzticami cilvēki. Ja administratora konts tiek pazaudēts, php artisan bookstack:create-admin izveido citu, bet php artisan bookstack:reset-mfa noņem lietotāja divfaktoru autentifikāciju.

Rezerves kopijas un atjauninājumi

Pilna rezerves kopija apvieno datubāzi un četras jūsu instancei raksturīgās failu vietas. Satura eksporti kalpo citam: dokumentācija precizē, ka tie rezerves kopiju neaizstāj.

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

Pirmā rinda paredzēta instalācijai ar skriptu, kur MySQL root pieslēdzas ar sudo; citur rakstiet mysqldump -u bookstack -p bookstack. Novietojiet šos divus failus atsevišķi, vēlams uz citas mašīnas. Arhīvā ir .env, tātad APP_KEY un jūsu paroles: izturieties pret to kā pret noslēpumu.

Atjaunošana

Uz jaunas mašīnas uzstādiet BookStack, nepalaižot php artisan migrate, soli, kas jāiekomentē skriptā, ja to izmantojat, pēc tam atjaunojiet datubāzi un failus, paturot sākotnējo APP_KEY:

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

Ja uzstādītā versija ir jaunāka par rezerves kopiju, pēc tam palaidiet php artisan migrate. Atjaunotajām mapēm atkal uzlieciet tīmekļa servera rakstīšanas tiesības. Ja adrese ir mainījusies, labojiet APP_URL un palaidiet bookstack:update-url.

Atjaunināšana

Pirms katra atjauninājuma izveidojiet datubāzes un failu rezerves kopiju, pēc tam no BookStack mapes:

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 skripts BookStack uzstāda bez Composer. Atjauninājumu lapa tad piedāvā, beta statusā, ./bookstack-system-cli download-vendor komandas composer install --no-dev vietā. Šis pats rīks prot veidot rezerves kopiju un atjaunot, taču projekts to vēl neuzskata par gatavu produkcijai: pārbaudiet to, pirms uz to paļaujaties.

Dokumentācija uztur sarakstu ar katrai versijai raksturīgiem norādījumiem, kas jāizlasa mērķa versijai. Daži piemēri:

• Versija 26.09: APP_KEY kļūst obligāts.
• Versija 26.05: mapei storage/fonts jāpaliek ar tīmekļa servera rakstīšanas tiesībām, citādi PDF eksporti var neizdoties.
• Versija 26.03: pēc atjauninājuma izmēģiniet e-pastu sūtīšanu.
• Versija 25.11: lielas datubāzes izmaiņas, kuru migrācija uz lielas instances var aizņemt vairākas minūtes.

Ievainojamības tiek labotas uzturēšanas versijās, piemēram, 26.09.3 no 2026. gada 11. novembra: melnraksta statusā esošas vai atkritnē pārvietotas lapas attēli un zīmējumi joprojām bija pieejami un maināmi, un redaktora personīgais melnraksts varēja kļūt redzams citiem cilvēkiem.

Kurš ko dara Managed VPS serverī

Mitināšana savā serverī prasa uzturēt serveri papildus lietojumprogrammai. Ar Managed VPS mūsu komandas uzņemas serveri un proaktīvi seko jūsu instancei; BookStack paliek jūsu programmatūra ar saviem iestatījumiem un datiem.

Ja vēlaties, lai mūsu komandas iejaucas pašā lietojumprogrammā, šis pakalpojums tiek rēķināts par stundu vai par fiksētu summu, ar novērtējumu, kas paziņots pirms iejaukšanās.