VPS voor BookStack: een zelfgehoste teamwiki

Teamdocumentatie sterft meestal op een van twee manieren: verspreid over chatthreads waarin niemand kan zoeken, of begraven in een wiki die zo onhandig is dat niemand hem bijwerkt. BookStack is die zeldzame zelfgehoste wiki die mensen echt gebruiken. Content staat op planken, in boeken, hoofdstukken en pagina's — een structuur die iedereen zonder training snapt. En het vraagt amper server.

Waarom BookStack

• Voor de hand liggende structuur. Boeken en hoofdstukken in plaats van een platte stapel pagina's.
• Bewerken dat niemand afschrikt. Standaard een WYSIWYG-editor, Markdown voor wie dat liever heeft.
• Echte rechten. Rollen per plank, boek of pagina — houd HR-documenten weg bij externe krachten.
• Bedrijfslogin. LDAP, SAML2 en OpenID Connect zitten erin.
• Jouw data. Alles staat in een MariaDB-database en een map op je server.

Het is niet het juiste gereedschap voor alles. Ontwikkelaarsdocumentatie die samen met de code moet veranderen, hoort in de repository, niet in een wiki.

Wat het nodig heeft

BookStack is licht. Voor de meeste teams is Micro-IP — 1 vCPU, 2 GB, $10 per maand — ruim voldoende. Het dedicated IP zorgt ervoor dat collega's het via HTTPS op je domein bereiken. De schijf groeit met geüploade screenshots en pdf's, niet met het aantal pagina's.

Installatie met Docker Compose

We gebruiken de veelgebruikte images van LinuxServer.io. Genereer eerst een applicatiesleutel:

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

Kopieer de base64:...-waarde die hij toont. Maak daarna docker-compose.yml aan:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=https://wiki.example.com
      - APP_KEY=base64:paste-your-key-here
      - DB_HOST=db
      - DB_PORT=3306
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=change-me
    volumes:
      - ./bookstack:/config
    ports:
      - 127.0.0.1:6875:80
    depends_on:
      - db
    restart: unless-stopped
  db:
    image: lscr.io/linuxserver/mariadb:latest
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=change-me-too
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=change-me
    volumes:
      - ./db:/config
    restart: unless-stopped

docker compose up -d
docker compose logs -f bookstack

APP_URL moet overeenkomen met het adres dat mensen gaan gebruiken, inclusief https://. Zit je ernaast, dan breken afbeeldingen en links op vreemde manieren. Meer over Compose in onze handleiding voor het uitrollen van een stack.

HTTPS en eerste login

Laat een subdomein naar de server wijzen (hoe), zet nginx voor 127.0.0.1:6875 en voeg een certificaat toe met certbot — de reverse proxy-handleiding loopt het met je door.

Log daarna in met het standaardaccount: admin@admin.com / password. Wijzig het e-mailadres en wachtwoord meteen, voordat je de link deelt. Alle anderen krijgen een eigen account of loggen in via jullie identiteitsprovider.

Back-ups

Twee dingen om te beschermen: de database en de uploads in ./bookstack. Een nachtelijke taak als deze dekt de database:

docker compose exec -T db mysqldump -u bookstack -pchange-me bookstack > /var/backups/bookstack.sql

Back-up daarna /var/backups en de compose-map extern — precies wat onze restic-handleiding doet. Managed Backups voegen daar dagelijkse herstelpunten van de hele server aan toe.

Onderhoud

Bijwerken is docker compose pull && docker compose up -d. BookStack draait zijn databasemigraties bij het opstarten. Lees de release notes voor hoofdversies; ze zijn kort en duidelijk.

Wil je team ook een plek voor tickets en code, dan past een zelfgehoste Git-server er mooi naast, op hetzelfde soort plan.