Hosta BookStack på en Managed VPS: din dokumentation hos dig

Det BookStack gör

BookStack är en dokumentationsplattform som är gjord för att förbli enkel: dess README siktar på att man kommer igång direkt, med enkla kunskaper i ordbehandling. Dina team skriver sina rutiner, sin dokumentation och sin kunskapsbas där, i en webbläsare, på det språk de föredrar.

• Fyra nivåer av ordning: hyllorna samlar böcker, böckerna innehåller kapitel och sidor, kapitlen är valfria, och innehållet finns i sidorna.
• Två redigerare: en visuell redigerare som standard och en Markdown-redigerare med liveförhandsvisning, till vilka diagrammen från diagrams.net läggs.
• Sökningen: i en bok, eller i alla böcker, kapitel och sidor.
• Rättigheterna: roller för hela systemet och behörigheter som gäller en hylla, en bok, ett kapitel eller en sida.
• Inloggningarna: e-post och lösenord, OpenID Connect, SAML 2.0, LDAP, med tvåfaktorsautentisering via app eller reservkoder, som kan göras obligatorisk per roll.
• Uppföljning och utbyte: historiken över varje sidas revisioner, ett REST-API och export till HTML, PDF, text, Markdown eller portabel ZIP.

Projektet står för sina val: dess README anger att BookStack inte är tänkt som en plattform som kan byggas ut för andra användningar, och det förblir bundet till dokumentation. Dess PDF-rendering går via dompdf, utan någon ytterligare installation, med begränsade möjligheter; projektet dokumenterar andra motorer med EXPORT_PDF_COMMAND.

Det som MIT-licensen tillåter

BookStack publiceras under MIT-licensen av Dan Brown och projektets bidragsgivare. Den tillåter all användning, alla ändringar och all distribution, på ett villkor: upphovsrättsmeddelandet och licenstexten ska finnas kvar i varje kopia av programvaran. Projektets FAQ anger att den attributionen gäller koden du delar: ingenting tvingar dig att visa namnet eller logotypen för BookStack på din instans.

Projektet håller sig till en enda version, fri och kostnadsfri: det erbjuder ingen företagsutgåva, och det har ingen officiell hosting, eller planer på att öppna någon. Det säljer däremot supportplaner, som bidrar till finansieringen tillsammans med donationer och sponsring. BookStack installeras alltså på din server, utan att du köper någon licens.

Kraven för BookStack

Docker är valfritt. Projektet publicerar ingen officiell avbild: installationerna i containrar kommer från communityprojekt, LinuxServer.io och solidnerd. Den här guiden följer den officiella vägen, PHP och MySQL direkt på servern, som inte kräver något mer.

Dokumentationen avråder från delad PHP-hosting: BookStack kräver en server som du själv administrerar. Den anger varken minne eller processor. På en Managed VPS beskriver du hur du tänker använda den, antalet personer och volymen av bilder och bilagor, så rekommenderar vi lämplig storlek.

Installationen av BookStack

Projektet erbjuder två vägar: ett skript för Ubuntu, det kortaste på en ny server, och en manuell installation för alla andra fall.

Med projektets skript, på en helt ny 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

De här skripten är förbehållna ett nyinstallerat system: de kan skriva över en befintlig webbkonfiguration. De lämnar också två saker därhän, e-postinställningarna och systemets säkerhet, som du får ordna separat.

Skriptet lägger BookStack i /var/www/bookstack. Skriptet för Ubuntu 26.04 frågar efter domänen och administratörskontots adress och visar sedan på slutet ett slumpmässigt lösenord, som inte finns i dess logg: anteckna det. Med ett annat skript noterar du åtkomstuppgifterna som visas på slutet och ändrar varje standardåtkomst vid första inloggningen.

För hand, på varje annan maskin

Börja med databasen: en databas och en användare som är begränsad till den. Projektets skript gör så, med det lösenord du väljer i stället för 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;"

Hämta sedan grenen release, sätt de rättigheter som dokumentationen anger för /var/www/bookstack och installera sedan beroendena:

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

Fyll i databasen och 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

Peka till sist webbroten på mappen public: DocumentRoot på Apache, root på Nginx. Utan Apache, eller när filerna .htaccess är avstängda, lägger du till omskrivningsreglerna för adresser: projektet publicerar exempel för Apache och för Nginx.

En manuell installation öppnas med kontot admin@admin.com och lösenordet password. Byt adress och lösenord vid första inloggningen.

HTTPS och APP_URL

Besökarna kommer in på port 80 och 443, under serverns domännamn. Skapa A- och AAAA-poster för det namnet och begär sedan certifikatet: skriptet för Ubuntu 26.04 konfigurerar Apache enbart på port 80, och installationssidan överlåter HTTPS åt dig. Certbot installerar certifikatet från Let’s Encrypt, anpassar Apache och förnyar certifikatet på egen hand. Under Nginx ersätter 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

Sätt sedan adressen till HTTPS i .env. APP_URL måste motsvara exakt den adress man besöker, prefixet inräknat: en avvikelse syns som saknade stilar, orimligt stora ikoner och trasiga menyer. En adress i https aktiverar säkra cookies av sig själv.

APP_URL=https://docs.example.com

Om det redan finns sidor behåller deras länkar den gamla adressen i databasen. Säkerhetskopiera databasen och kör sedan projektets kommando:

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

BookStack serveras i roten av en domän eller underdomän, och dokumentationen beskriver också en installation under en undermapp, som example.com/bookstack. Om en omvänd proxy läggs framför Apache anger du dess adress i APP_PROXIES: utan den ser granskningsloggen och hastighetsbegränsningen proxyns adress i stället för besökarnas. Dokumentationen reserverar APP_PROXIES="*" för felsökning.

Var dina data finns

Behåll samma APP_KEY över tid och säkerhetskopiera den. BookStack använder den för att kryptera bland annat hemligheterna för tvåfaktorsautentisering: att byta den kan bryta de funktionerna, och sedan version 26.09 ger applikationen ett fel om den saknas.

Bilderna är publika som standard

Med standardlagringen serverar webbservern bilderna direkt, vilket går snabbt, och den som känner till deras adress kan öppna dem. För intern dokumentation görs valet i STORAGE_TYPE:

För stora filer ska tre inställningar stämma överens: FILE_UPLOAD_SIZE_LIMIT i .env, post_max_size och upload_max_filesize i php.ini, och client_max_body_size under Nginx, som är 1 MB som standard.

Två inställningar betyder också något för levande dokumentation: varje sida behåller 100 revisioner som standard (REVISION_LIMIT), och papperskorgen behåller borttagna objekt i 30 dagar (RECYCLE_BIN_LIFETIME).

E-post: SMTP och kö

BookStack skickar e-post för bekräftelse av adresser, bortglömda lösenord, inbjudningar och aviseringar. Från en VPS hos Simafri går utskicken via ett autentiserat SMTP-relä, på port 587: adressen till ett e-postkonto som du redan 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

Kontrollera resultatet under ”Settings”, ”Maintenance”, med åtgärden ”Send a Test Email”, som visar de fel som uppstått. Ett misslyckande vid en inbjudan visas på skärmen, medan ett misslyckande vid en avisering stannar i applikationens logg.

Skicka i bakgrunden

Som standard skickar BookStack e-post och webhooks under själva förfrågan, vilket kan göra sidorna långsammare. För att gå över till bakgrunden skriver du QUEUE_CONNECTION=database i .env och kör en tjänst, med exemplet som dokumentationen ger för en Ubuntu-installation med skript:

[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

Säkra din BookStack-instans

Säkerhetsdokumentationen ger en lista att gå igenom redan vid installationen:

1. Byt adress och lösenord för den första administratören.
2. Kontrollera att webbservern serverar enbart mappen public, särskilt om BookStack ligger under /var/www.
3. Begränsa databasanvändaren till BookStacks databas.
4. Fyll i APP_URL, så att adresserna som systemet genererar inte kan manipuleras.
5. Gå igenom inställningarna för registrering och publik åtkomst, därefter rollerna.

Tvåfaktorsautentiseringen kan sedan göras obligatorisk per roll. Prenumerera också på projektets e-postlista för säkerhet, för att få dess varningar. Adressen /status används för övervakning: den svarar 200 när allt är bra, och en felkod lika med eller över 400 annars.

PHP betyder lika mycket som BookStack. Projektet publicerade den 21 oktober 2026 en varning om en kritisk uppdatering av PHP, rättad i 8.5.12, 8.4.27, 8.3.36 och 8.2.35. Ubuntu publicerar de här rättelserna under egna paketnummer, som 8.3.6-0ubuntu0.24.04.13 för Ubuntu 24.04.

För ditt innehåll, behåll filtreringen som är aktiv som standard och reservera dess uppmjukning för instanser där bara betrodda personer skriver. Om ett administratörskonto går förlorat skapar php artisan bookstack:create-admin ett annat, och php artisan bookstack:reset-mfa tar bort en användares tvåfaktorsautentisering.

Säkerhetskopior och uppdateringar

En fullständig säkerhetskopia samlar databasen och de fyra filplatser som hör till din instans. Exporterna av innehåll tjänar ett annat syfte: dokumentationen anger att de inte ersätter en säkerhetskopia.

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

Den första raden gäller en installation med skript, där MySQL:s root ansluter via sudo; på andra håll skriver du mysqldump -u bookstack -p bookstack. Lägg de två filerna för sig, helst på en annan maskin. Arkivet innehåller .env, alltså APP_KEY och dina lösenord: behandla det som en hemlighet.

Återställa

På en ny maskin installerar du BookStack utan att köra php artisan migrate, ett steg som kommenteras bort i skriptet om du använder det, och återställer sedan databasen och filerna, med den ursprungliga APP_KEY i behåll:

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

Om den installerade versionen är nyare än säkerhetskopian kör du därefter php artisan migrate. Sätt tillbaka webbserverns skrivrättigheter på de återställda mapparna. Om adressen har ändrats rättar du APP_URL och kör bookstack:update-url.

Uppdatera

Säkerhetskopiera databasen och filerna före varje uppdatering och kör sedan, från BookStacks mapp:

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

Skriptet för Ubuntu 26.04 installerar BookStack utan Composer. Sidan om uppdateringar föreslår då, i beta, ./bookstack-system-cli download-vendor i stället för composer install --no-dev. Samma verktyg kan säkerhetskopiera och återställa, men projektet anser det inte ännu moget för produktion: testa det innan du förlitar dig på det.

Dokumentationen har en lista med anvisningar för varje version, att läsa för den version du siktar på. Några exempel:

• Version 26.09: APP_KEY blir obligatorisk.
• Version 26.05: mappen storage/fonts måste förbli skrivbar för webbservern, annars kan PDF-exporterna misslyckas.
• Version 26.03: prova e-postutskicket efter uppdateringen.
• Version 25.11: stora ändringar i databasen, vars migrering kan ta flera minuter på en stor instans.

Säkerhetsbristerna rättas i underhållsversioner, som 26.09.3 från den 11 november 2026: bilder och ritningar på en sida som var ett utkast eller låg i papperskorgen förblev åtkomliga och kunde ändras, och en redaktörs personliga utkast kunde bli synligt för andra personer.

Vem gör vad på en Managed VPS

Att självhosta innebär att sköta servern utöver applikationen. På en Managed VPS tar våra team hand om servern och följer din instans proaktivt; BookStack förblir din programvara, med sina inställningar och sina data.

Om du föredrar att våra team ingriper i själva applikationen faktureras den tjänsten per timme eller som fast pris, med en offert som lämnas före ingreppet.