BookStack hosten op een Managed VPS: uw documentatie in eigen beheer

Wat BookStack doet

BookStack is een documentatieplatform dat bewust eenvoudig is gehouden: de README mikt op een directe ingebruikname, met simpele kennis van tekstverwerking. Uw teams schrijven er hun procedures, hun documentatie en hun kennisbank, in een browser, in het Nederlands als ze dat willen.

• Vier niveaus van ordening: de planken bundelen boeken, de boeken bevatten hoofdstukken en pagina's, de hoofdstukken zijn optioneel, en de inhoud leeft in de pagina's.
• Twee editors: een visuele editor als standaard en een Markdown-editor met live voorbeeld, aangevuld met de schema's van diagrams.net.
• Zoeken: in een boek, of in alle boeken, hoofdstukken en pagina's.
• De rechten: rollen voor het hele systeem, en rechten die eigen zijn aan een plank, een boek, een hoofdstuk of een pagina.
• De aanmeldingen: e-mail en wachtwoord, OpenID Connect, SAML 2.0, LDAP, met tweestapsverificatie via een app of reservecodes, die per rol kan worden opgelegd.
• Opvolging en uitwisseling: de revisiegeschiedenis van elke pagina, een REST-API, en export naar HTML, pdf, tekst, Markdown of draagbare ZIP.

Het project staat achter zijn keuzes: de README preciseert dat BookStack niet is ontworpen als uitbreidbaar platform voor andere toepassingen, en het blijft bij de documentatie. De pdf-weergave loopt via dompdf, zonder extra installatie, met beperkte mogelijkheden; het project documenteert andere engines met EXPORT_PDF_COMMAND.

Wat de MIT-licentie toestaat

BookStack wordt gepubliceerd onder de MIT-licentie door Dan Brown en de bijdragers van het project. Ze staat elk gebruik, elke wijziging en elke verspreiding toe, onder één voorwaarde: de copyrightvermelding en de tekst van de licentie blijven in elke kopie van de software staan. De FAQ van het project preciseert dat deze naamsvermelding de code betreft die u deelt: niets verplicht u de naam of het logo van BookStack op uw instantie te tonen.

Het project houdt één enkele, vrije en gratis versie aan: het biedt geen enterpriseversie en heeft geen officiële hosting, noch plannen om er een te openen. Het verkoopt wel supportpakketten, die samen met donaties en sponsoring bijdragen aan de financiering. BookStack installeert u dus op uw server, zonder een licentie te kopen.

De vereisten van BookStack

Docker blijft optioneel. Het project publiceert geen officiële image: installaties in containers komen van communityprojecten, LinuxServer.io en solidnerd. Deze gids volgt de officiële weg, PHP en MySQL rechtstreeks op de server, die niets extra vraagt.

De documentatie raadt gedeelde PHP-hosting af: BookStack vraagt een server die u zelf beheert. Ze noemt geen cijfers voor het benodigde geheugen en de benodigde processor. Beschrijf op een managed VPS uw gebruik, het aantal personen en het volume aan afbeeldingen en bijlagen aan ons, dan raden wij u de passende grootte aan.

De installatie van BookStack

Het project biedt twee wegen: een script voor Ubuntu, het kortst op een nieuwe server, en een handmatige installatie voor alle andere gevallen.

Met het script van het project, op een gloednieuwe 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

Deze scripts zijn voorbehouden aan een vers geïnstalleerd systeem: ze kunnen een bestaande webconfiguratie overschrijven. Ze laten ook twee onderwerpen buiten beschouwing, de e-mailinstellingen en de beveiliging van het systeem, die u apart moet regelen.

Het script plaatst BookStack in /var/www/bookstack. Dat van Ubuntu 26.04 vraagt het domein en het adres van het beheerdersaccount en toont aan het eind een willekeurig getrokken wachtwoord, dat niet in zijn logboek staat: noteer het. Neem bij een ander script de toegangsgegevens over die aan het eind verschijnen en wijzig elke standaardtoegang bij de eerste aanmelding.

Met de hand, op elke andere machine

Begin met de database: een database en een gebruiker die tot die database is beperkt. Het script van het project gaat zo te werk, met het wachtwoord van uw keuze in plaats van 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;"

Haal daarna de tak release op, stel de rechten in die de documentatie voor /var/www/bookstack geeft en installeer de afhankelijkheden:

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

Vul de database en het adres in .env in:

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

Laat ten slotte de webroot naar de map public wijzen: DocumentRoot op Apache, root op Nginx. Zonder Apache, of wanneer de bestanden .htaccess zijn uitgeschakeld, voegt u de regels voor het herschrijven van adressen toe: het project publiceert voorbeelden voor Apache en voor Nginx.

Een handmatige installatie opent met het account admin@admin.com en het wachtwoord password. Wijzig het adres en het wachtwoord bij de eerste aanmelding.

HTTPS en APP_URL

De bezoekers komen binnen op de poorten 80 en 443, onder de domeinnaam van de server. Maak voor die naam A- en AAAA-records aan en vraag daarna het certificaat aan: het script van Ubuntu 26.04 configureert Apache alleen op poort 80, en de installatiepagina laat HTTPS aan u over. Certbot plaatst het Let's Encrypt-certificaat, past Apache aan en vernieuwt het certificaat vanzelf. Vervang onder Nginx --apache door --nginx.

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

Zet daarna het adres op HTTPS in .env. APP_URL moet exact overeenkomen met het adres waarmee u bezoekt, voorvoegsel inbegrepen: een afwijking herkent u aan ontbrekende stijlen, buitensporig grote pictogrammen en kapotte menu's. Een adres in https activeert vanzelf de beveiligde cookies.

APP_URL=https://docs.example.com

Bestaan er al pagina's, dan houden hun links het oude adres in de database. Maak een back-up van de database en voer dan de opdracht van het project uit:

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

BookStack wordt aangeboden op de root van een domein of subdomein, en de documentatie beschrijft ook een installatie onder een submap, zoals example.com/bookstack. Komt er een reverse proxy voor Apache, geef dan zijn adres op in APP_PROXIES: zonder dat zien het auditlogboek en de snelheidsbeperking het adres van de proxy in plaats van dat van de bezoekers. De documentatie behoudt APP_PROXIES="*" voor diagnose.

Waar uw gegevens staan

Houd dezelfde APP_KEY aan op de lange termijn en maak er een back-up van. BookStack gebruikt haar onder meer om de geheimen van de tweestapsverificatie te versleutelen: haar wijzigen kan deze functies breken, en sinds versie 26.09 geeft de applicatie een fout als ze ontbreekt.

De afbeeldingen zijn standaard openbaar

Met de standaardopslag bedient de webserver de afbeeldingen rechtstreeks, wat snel gaat, en iedereen die hun adres kent, kan ze openen. Voor een interne documentatie maakt u de keuze in STORAGE_TYPE:

Voor zware bestanden moeten drie instellingen op elkaar worden afgestemd: FILE_UPLOAD_SIZE_LIMIT in .env, post_max_size en upload_max_filesize in php.ini, en client_max_body_size onder Nginx, dat standaard 1 MB is.

Twee instellingen tellen ook voor een levende documentatie: elke pagina bewaart standaard 100 revisies (REVISION_LIMIT), en de prullenbak bewaart verwijderde items 30 dagen (RECYCLE_BIN_LIFETIME).

E-mails: SMTP en wachtrij

BookStack verstuurt e-mails voor de bevestiging van adressen, een vergeten wachtwoord, uitnodigingen en meldingen. Vanaf een Simafri-VPS loopt het verzenden via een geauthenticeerde SMTP-relay, op poort 587: het adres van een e-mailaccount dat u al hebt, of 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

Controleer het resultaat in “Settings”, “Maintenance”, met de actie “Send a Test Email”, die de opgetreden fouten toont. Een mislukte uitnodiging verschijnt op het scherm, terwijl een mislukte melding in het logboek van de applicatie blijft.

Op de achtergrond verzenden

Standaard verstuurt BookStack e-mails en webhooks tijdens het verzoek, wat de pagina's kan vertragen. Om naar de achtergrond over te stappen, schrijft u QUEUE_CONNECTION=database in .env en laat u een service draaien, met het voorbeeld dat de documentatie geeft voor een Ubuntu-installatie met het 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

Uw BookStack-instantie beveiligen

De beveiligingsdocumentatie geeft een lijst die u vanaf de installatie overneemt:

1. Wijzig het adres en het wachtwoord van de eerste beheerder.
2. Controleer dat de webserver alleen de map public bedient, vooral als BookStack onder /var/www staat.
3. Beperk de gebruiker van de database tot alleen de database van BookStack.
4. Vul APP_URL in, zodat de door het systeem gegenereerde adressen niet kunnen worden gemanipuleerd.
5. Lees de instellingen voor registratie en openbare toegang na, en daarna de rollen.

De tweestapsverificatie legt u daarna per rol op. Schrijf u ook in op de beveiligingsmailinglijst van het project, om zijn waarschuwingen te ontvangen. Het adres /status dient voor monitoring: het antwoordt 200 als alles goed gaat, en anders met een foutcode van 400 of hoger.

PHP telt evenveel mee als BookStack. Het project publiceerde op 21 oktober 2026 een waarschuwing over een kritieke update van PHP, verholpen in 8.5.12, 8.4.27, 8.3.36 en 8.2.35. Ubuntu publiceert deze fixes onder zijn eigen pakketnummers, zoals 8.3.6-0ubuntu0.24.04.13 voor Ubuntu 24.04.

Laat voor uw inhoud de standaard ingeschakelde filtering aan staan, en behoud het versoepelen ervan voor instanties waar alleen vertrouwde personen schrijven. Raakt u een beheerdersaccount kwijt, dan maakt php artisan bookstack:create-admin een ander aan, en haalt php artisan bookstack:reset-mfa de tweestapsverificatie van een gebruiker weg.

Back-ups en updates

Een volledige back-up omvat de database en de vier bestandslocaties die bij uw instantie horen. De inhoudsexports dienen ergens anders voor: de documentatie preciseert dat ze geen back-up vervangen.

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

De eerste regel is bedoeld voor een installatie met het script, waar de root van MySQL via sudo verbindt; schrijf elders mysqldump -u bookstack -p bookstack. Berg deze twee bestanden apart op, bij voorkeur op een andere machine. Het archief bevat .env, dus APP_KEY en uw wachtwoorden: behandel het als een geheim.

Terugzetten

Installeer BookStack op een nieuwe machine zonder php artisan migrate uit te voeren, een stap die u in het script als commentaar zet als u het gebruikt, en zet daarna de database en de bestanden terug, met behoud van de oorspronkelijke APP_KEY:

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

Is de geïnstalleerde versie nieuwer dan de back-up, voer dan daarna php artisan migrate uit. Geef de webserver weer schrijfrechten op de teruggezette mappen. Is het adres gewijzigd, corrigeer dan APP_URL en voer bookstack:update-url uit.

Bijwerken

Maak vóór elke update een back-up van de database en de bestanden en voer dan, vanuit de map van BookStack, uit:

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

Het script voor Ubuntu 26.04 installeert BookStack zonder Composer. De updatepagina stelt dan, in bèta, ./bookstack-system-cli download-vendor voor in plaats van composer install --no-dev. Dezelfde tool kan ook back-ups maken en terugzetten, maar het project vindt hem nog niet klaar voor productie: test hem voordat u erop vertrouwt.

De documentatie houdt een lijst bij met richtlijnen per versie, te lezen voor de beoogde versie. Enkele voorbeelden:

• Versie 26.09: APP_KEY wordt verplicht.
• Versie 26.05: de map storage/fonts moet voor de webserver beschrijfbaar blijven, anders kunnen pdf-exports mislukken.
• Versie 26.03: probeer het verzenden van e-mails uit na de update.
• Versie 25.11: grote wijzigingen in de database, waarvan de migratie op een grote instantie enkele minuten kan duren.

Kwetsbaarheden worden verholpen in onderhoudsversies, zoals 26.09.3 van 11 november 2026: afbeeldingen en tekeningen van een pagina die nog een concept was of in de prullenbak lag, bleven bereikbaar en aanpasbaar, en het persoonlijke concept van een redacteur kon zichtbaar worden voor andere personen.

Wie doet wat op een managed VPS

Self-hosting vraagt dat u naast de applicatie ook de server beheert. Op een managed VPS neemt ons team de server voor zijn rekening en houdt het uw instantie proactief in de gaten; BookStack blijft uw software, met zijn instellingen en gegevens.

Wilt u liever dat ons team in de applicatie zelf ingrijpt, dan wordt die dienstverlening per uur of tegen een vast bedrag gefactureerd, met een offerte voordat het werk begint.