Hoste BookStack på en Managed VPS: din dokumentation hos dig selv

Hvad BookStack gør

BookStack er en dokumentationsplatform, der er tænkt til at forblive enkel: dens README sigter mod en øjeblikkelig ibrugtagning med blot nogle få begreber fra tekstbehandling. Dine teams skriver deres procedurer, deres dokumentation og deres vidensbase der, i en browser, på dansk, hvis de ønsker det.

• Fire niveauer af ordning: hylderne samler bøger, bøgerne rummer kapitler og sider, kapitlerne er valgfrie, og indholdet lever i siderne.
• To editorer: en visuel editor som standard og en Markdown-editor med live-eksempelvisning, hvortil kommer diagrammerne fra diagrams.net.
• Søgningen: i en bog eller på tværs af alle bøger, kapitler og sider.
• Rettighederne: roller for hele systemet og tilladelser, der er specifikke for en hylde, en bog, et kapitel eller en side.
• Loginmulighederne: e-mail og adgangskode, OpenID Connect, SAML 2.0, LDAP, med tofaktorgodkendelse via app eller nødkoder, som kan gøres obligatorisk pr. rolle.
• Sporingen og udvekslingen: historikken over hver sides revisioner, et REST-API og eksport til HTML, PDF, tekst, Markdown eller bærbar ZIP.

Projektet står ved sine valg: dets README præciserer, at BookStack ikke er udformet som en platform, der kan udvides til andre formål, og det forbliver forpligtet på dokumentationen. Dets PDF-rendering går gennem dompdf, uden yderligere installation, med begrænsede muligheder; projektet dokumenterer andre motorer med EXPORT_PDF_COMMAND.

Hvad MIT-licensen tillader

BookStack udgives under MIT-licensen af Dan Brown og projektets bidragydere. Den tillader enhver brug, enhver ændring og enhver distribution på én betingelse: at bevare copyright-meddelelsen og licensteksten i enhver kopi af softwaren. Projektets FAQ præciserer, at denne kreditering gælder den kode, du deler: intet forpligter dig til at vise BookStacks navn eller logo på din instans.

Projektet fører kun én version, fri og gratis: det tilbyder ikke en enterprise-udgave, og det har ingen officiel hosting eller planer om at åbne en. Det sælger til gengæld supportabonnementer, som sammen med donationer og sponsorater er med til at finansiere det. BookStack installeres altså på din server, uden at du skal købe en licens.

Kravene til BookStack

Docker er fortsat valgfrit. Projektet udgiver ikke et officielt image: installationerne i containere kommer fra fællesskabsprojekter, LinuxServer.io og solidnerd. Denne guide følger den officielle vej, PHP og MySQL direkte på serveren, som ikke kræver mere.

Dokumentationen fraråder delt PHP-hosting: BookStack kræver en server, du selv administrerer. Den opgiver hverken den nødvendige hukommelse eller processor. På en Managed VPS beskriver du blot din brug, antallet af personer og mængden af billeder og vedhæftede filer for os, og vi anbefaler den størrelse, der passer.

Installation af BookStack

Projektet tilbyder to veje: et script til Ubuntu, det korteste på en ny server, og en manuel installation i alle andre tilfælde.

Med projektets script, på en splinterny 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

Disse scripts er forbeholdt et nyinstalleret system: de kan overskrive en eksisterende webkonfiguration. De lader også to emner ligge, e-mailindstillingerne og systemets sikkerhed, som skal tages op for sig.

Scriptet lægger BookStack i /var/www/bookstack. Scriptet til Ubuntu 26.04 spørger efter domænet og administratorkontoens adresse og viser til sidst en tilfældigt trukket adgangskode, som ikke står i dets log: skriv den ned. Med et andet script skal du notere de adgange, der vises til sidst, og ændre enhver standardadgang ved første login.

Manuelt, på enhver anden maskine

Begynd med databasen: en database og en bruger, der er begrænset til denne database. Projektets script gør det sådan, med den adgangskode, du selv vælger i stedet for 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;"

Hent derefter grenen release, sæt de rettigheder, som dokumentationen angiver for /var/www/bookstack, og installér derefter afhængighederne:

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

Angiv databasen og adressen i .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

Peg til sidst webroden på mappen public: DocumentRoot på Apache, root på Nginx. Uden Apache, eller når filerne .htaccess er deaktiveret, tilføjer du reglerne for omskrivning af adresser: projektet udgiver eksempler til Apache og til Nginx.

En manuel installation åbnes med kontoen admin@admin.com og adgangskoden password. Ændr adressen og adgangskoden ved første login.

HTTPS og APP_URL

De besøgende kommer ind på port 80 og 443, under serverens domænenavn. Opret A- og AAAA-records for dette navn, og bed derefter om certifikatet: scriptet til Ubuntu 26.04 konfigurerer kun Apache på port 80, og installationssiden overlader HTTPS til dig. Certbot installerer certifikatet fra Let's Encrypt, tilpasser Apache og fornyer certifikatet af sig selv. Under Nginx erstatter du --apache med --nginx.

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

Skift derefter adressen til HTTPS i .env. APP_URL skal svare præcist til den adresse, der besøges, præfiks inklusive: en afvigelse viser sig ved manglende stilarter, overdimensionerede ikoner og ødelagte menuer. En adresse i https slår af sig selv de sikre cookies til.

APP_URL=https://docs.example.com

Hvis der allerede findes sider, beholder deres links den gamle adresse i databasen. Tag backup af databasen, og kør derefter projektets kommando:

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

BookStack serveres i roden af et domæne eller subdomæne, og dokumentationen beskriver også en installation under en undermappe, som example.com/bookstack. Hvis en reverse proxy sættes foran Apache, skal du angive dens adresse i APP_PROXIES: uden den ser revisionsloggen og begrænsningen af forespørgselshastighed proxyens adresse i stedet for de besøgendes. Dokumentationen forbeholder APP_PROXIES="*" til fejlfinding.

Hvor dine data ligger

Behold den samme APP_KEY over tid, og tag backup af den. BookStack bruger den blandt andet til at kryptere hemmelighederne til tofaktorgodkendelse: at ændre den kan ødelægge disse funktioner, og siden version 26.09 returnerer applikationen en fejl, hvis den mangler.

Billederne er offentlige som standard

Med standardlagringen serverer webserveren billederne direkte, hvilket går hurtigt, og enhver, der kender deres adresse, kan åbne dem. Til en intern dokumentation træffes valget i STORAGE_TYPE:

Til tunge filer skal tre indstillinger passe sammen: FILE_UPLOAD_SIZE_LIMIT i .env, post_max_size og upload_max_filesize i php.ini og client_max_body_size under Nginx, som er 1 MB som standard.

To indstillinger tæller også for en levende dokumentation: hver side beholder 100 revisioner som standard (REVISION_LIMIT), og papirkurven gemmer de slettede elementer i 30 dage (RECYCLE_BIN_LIFETIME).

E-mails: SMTP og kø

BookStack sender e-mails til bekræftelse af adresser, glemt adgangskode, invitationer og notifikationer. Fra en Simafri VPS går afsendelsen gennem et autentificeret SMTP-relay på port 587: adressen på en mailkonto, du allerede har, eller 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

Kontrollér resultatet under «Settings», «Maintenance», med handlingen «Send a Test Email», som viser de fejl, der opstår. En fejl ved en invitation vises på skærmen, mens en fejl ved en notifikation bliver i applikationens log.

Send i baggrunden

Som standard sender BookStack e-mails og webhooks under selve forespørgslen, hvilket kan gøre siderne langsommere. For at gå over til baggrunden skriver du QUEUE_CONNECTION=database i .env og kører en tjeneste, med det eksempel som dokumentationen giver for en Ubuntu-installation via 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

Sikr din BookStack-instans

Sikkerhedsdokumentationen giver en liste, der skal følges fra installationen:

1. Ændr adressen og adgangskoden til den første administrator.
2. Kontrollér, at webserveren kun serverer mappen public, især hvis BookStack ligger under /var/www.
3. Begræns databasebrugeren til BookStacks database alene.
4. Angiv APP_URL, så de adresser, systemet genererer, ikke kan manipuleres.
5. Gennemgå indstillingerne for tilmelding og offentlig adgang og derefter rollerne.

Tofaktorgodkendelsen gøres derefter obligatorisk pr. rolle. Tilmeld dig også projektets sikkerhedsmailingliste for at modtage dets alarmer. Adressen /status bruges til overvågning: den svarer 200, når alt er i orden, og ellers en fejlkode på 400 eller derover.

PHP tæller lige så meget som BookStack. Projektet udgav den 21. oktober 2026 en alarm om en kritisk PHP-opdatering, rettet i 8.5.12, 8.4.27, 8.3.36 og 8.2.35. Ubuntu udgiver disse rettelser under sine egne pakkenumre, som 8.3.6-0ubuntu0.24.04.13 for Ubuntu 24.04.

Til dit indhold bør du lade filtreringen, der er slået til som standard, være, og kun lempe den på instanser, hvor kun betroede personer skriver. Hvis en administratorkonto går tabt, opretter php artisan bookstack:create-admin en anden, og php artisan bookstack:reset-mfa fjerner en brugers tofaktorgodkendelse.

Backup og opdateringer

En komplet backup samler databasen og de fire filplaceringer, der er særlige for din instans. Indholdseksporterne bruges til noget andet: dokumentationen præciserer, at de ikke erstatter en backup.

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

Den første linje sigter mod en installation via script, hvor MySQL's root forbinder via sudo; andre steder skriver du mysqldump -u bookstack -p bookstack. Læg disse to filer for sig, helst på en anden maskine. Arkivet indeholder .env, altså APP_KEY og dine adgangskoder: behandl det som en hemmelighed.

Gendan

På en ny maskine installerer du BookStack uden at køre php artisan migrate, et trin der skal kommenteres ud i scriptet, hvis du bruger det, og gendanner derefter databasen og filerne, med den oprindelige APP_KEY bevaret:

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

Hvis den installerede version er nyere end backuppen, kører du derefter php artisan migrate. Sæt webserverens skriverettigheder på de gendannede mapper igen. Hvis adressen er ændret, skal du rette APP_URL og køre bookstack:update-url.

Opdatér

Tag backup af databasen og filerne før hver opdatering, og kør derefter, fra BookStacks mappe:

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

Scriptet til Ubuntu 26.04 installerer BookStack uden Composer. Opdateringssiden foreslår så, i beta, ./bookstack-system-cli download-vendor i stedet for composer install --no-dev. Det samme værktøj kan tage backup og gendanne, men projektet betragter det endnu ikke som klar til produktion: test det, før du stoler på det.

Dokumentationen fører en liste over anvisninger, der er særlige for hver version, som skal læses for den version, du sigter mod. Nogle eksempler:

• Version 26.09: APP_KEY bliver obligatorisk.
• Version 26.05: mappen storage/fonts skal forblive skrivbar for webserveren, ellers kan PDF-eksporterne fejle.
• Version 26.03: prøv afsendelse af e-mails efter opdateringen.
• Version 25.11: store ændringer i databasen, hvis migrering kan tage flere minutter på en stor instans.

Sårbarhederne rettes i vedligeholdelsesversioner, som 26.09.3 fra den 11. november 2026: billeder og tegninger på en side, der var en kladde eller lå i papirkurven, forblev tilgængelige og kunne ændres, og en redaktørs personlige kladde kunne blive synlig for andre personer.

Hvem gør hvad på en Managed VPS

Selvhosting kræver, at du holder serveren ud over selve applikationen. På en Managed VPS tager vores teams sig af serveren og følger din instans proaktivt; BookStack forbliver din software, med dens indstillinger og data.

Hvis du foretrækker, at vores teams griber ind i selve applikationen, faktureres den ydelse pr. time eller som fast pris, med et overslag oplyst før indgrebet.