Bookstack - Einführung und Installation

Bookstack ist eine Open Source Wiki Anwendung. Es verfügt über eine sehr ansprechende und responsive Weboberfläche. Das besondere an Bookstack ist die Einteilung von Informationen in Bücher, Kapitel und Seiten. Zusätzlich gibt es die Möglichkeit Bücher in sog. Regalen zusammenzufassen und so Thematisch zusammenzufassen. Dabei kann ein Buch in mehrere Regale aufgenommen werden, was die Duplizierung von Informationen vermeidet. Der WYSIWYG Editor macht es einfach Texte zu schreiben, alternativ können Texte im Markdown Format erfasst werden. Man kann die geschriebenen Texte wunderbar durch Bilder ergänzen und sogar mit Hilfe der nativen Integration von draw.io eigene Diagramme und Zeichnungen anfertigen und einbinden.

Ich persönlich nutze Bookstack vor allem zur Dokumentation meiner Infrastruktur.

Bookstack läuft unter der MIT License und erlaubt es so die Software kostenlos zu nutzen und bei Bedarf sogar zu erweitern. Der Source Code steht auf Github zur Verfügung.

Am einfachsten lässt sich Bookstack mit Hilfe von Docker installieren. In diesem Eintrag beschreibe ich die Installation über Docker Compose, inklusive eines MariaDB Datenbank Server. Für Produktionssysteme empfiehlt es sich einen standalone Datenbank Server zu verwenden oder je nach Verwendung und Verfügbarkeit sogar auf ein Galera Cluster oder PaaS Services diverser Cloudanbieter zurückzugreifen. So kann man sich komplett auf die Betreuung der Bookstack Instanz, inklusive Backup und Recovery konzentrieren und muss sich nicht zusätzlich um das Housekeeping der Datenbank kümmern. Ausserdem empfiehlt es sich einen Reverse Proxy, wie Traefik oder NGINX Proxy Manager einzusetzen, um Bookstack aus dem Internet oder auch dem lokalem Netzwerk erreichbar zu machen.

Vorraussetzungen

Folgende Vorraussetzungen müssen erfüllt sein, damit wir Bookstack installieren können:

Docker und Docker Compose muss auf dem Rechner installiert sein, auf dem wir Bookstack installieren wollen.

Zusätzlich empfiehlt sich der Einsatz eines Reverse Proxy, z.B. NGINX Proxy Manager, um die Anwendung sicher von außen Verfügbar zu machen.

Vorbereitungen

Docker Compose

Für die Installation nutzen wir Docker Compose. Dies macht es einfacher den kompletten Stack zu installieren.

mkdir -p bookstack
cd bookstack
nano docker-compose.yaml

docker-compose.yaml

version: "3.9"

services:

  bookstack:
    image: linuxserver/bookstack:23.10.4
    container_name: bookstack
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - APP_ENV=$APP_ENV
      - APP_DEBUG=$APP_DEBUG
      - APP_KEY=$APP_KEY
      - APP_URL=$APP_URL
      - APP_LANG=$APP_LANG
      - APP_AUTO_LANG_PUBLIC=$APP_AUTO_LANG_PUBLIC
      - APP_TIMEZONE=$APP_TIMEZONE
      - DB_HOST=$DB_HOST
      - DB_PORT=$DB_PORT
      - DB_DATABASE=$DB_NAME
      - DB_USERNAME=$DB_USERNAME
      - DB_PASSWORD=$DB_PASSWORD
      - SESSION_LIFETIME=$SESSION_LIFETIME
      - AUTH_METHOD=$AUTH_METHOD
    volumes:
      - bookstack-data:/config
    networks:
      - bookstack-net
    ports:
      - 8080:80
    healthcheck: 
      test: ["CMD-SHELL", " wget --spider http://localhost:80/status"]
      interval: 10s
      retries: 5
      timeout: 3s

  bookstack-db:
    image: mariadb:11.2
    container_name: bookstack-db
    restart: unless-stopped
    environment:
      - MARIADB_ROOT_PASSWORD=$DB_ROOT_PASSWORD
      - MARIADB_DATABASE=$DB_NAME
      - MARIADB_USER=$DB_USERNAME
      - MARIADB_PASSWORD=$DB_PASSWORD
    volumes:
      - bookstack-db-data:/var/lib/mysql
    networks:
      - bookstack-net
    healthcheck: 
      test: ["CMD-SHELL", " healthcheck.sh --connect --innodb_initialized"]
      interval: 5s
      retries: 5
      timeout: 3s

volumes:
  bookstack-data:
    name: bookstack-data
  bookstack-db-data:
    name: bookstack-db-data

networks:
  bookstack-net:
    name: bookstack-net

Umgebungsvariablen

Folgende Umgebungsvariablen müssen angepasst werden

Umgebungsvariable	Beschreibung	Beispiel
`ÀPP_ENV`	Die Umgebung in der Bookstack ausgeführt wird	production
`APP_DEBUG`	Aktiviert erweiterte Optionen für das Debugging	false
`APP_KEY`	Wird zur Verschlüsselung einiger Daten benötigt. Sollte man über eine Laravel Installation verfügen, kann man den folgenden Befehl verwenden: `php artisan key:generate` . Alternativ besteht die Möglichkeit sich einen Schlüssel auf der folgenden Website erzeugen zu lassen: https://laravel-encryption-key-generator.vercel.app/	base64:<>
`APP_URL`	Die Root URL unter der Bookstack erreichbar ist	http://localhost:8080
`APP_LANG`	Die Standardsprache, welche von Bookstack verwendet werden soll	de
`APP_AUTO_LANG_PUBLIC`	Automatisches erkennen der Sprache des Benutzers anhand der Browser Sprache. Wenn die Information nicht im Header übermittelt wird, gilt `APP_LANG`	true
`APP_TIMEZONE`	Die Zeitzone in welcher Zeitbezogene Informationen angezeigt werden sollen. Gültige Zeitzonen können hier abgerufen werden: https://www.php.net/manual/en/timezones.php	Europe/Berlin
`AUTH_METHOD`	Die Authentifizierungsmethode. Die Konfiguration von externen Authentifizierungsmethoden, wie OpenID, werden später folgen	standard
`DB_ROOT_PASSWORD`	Das Root Password für die MariaDB	<>
`DB_HOST`	Hostname oder IP der Datenbank	bookstack-db
`DB_PORT`	Port der Datenbank	3306
`DB_NAME`	Datenbankname	bookstack
`DB_USERNAME`	Username für die Datenbank Verbindung	bookstack
`DB_PASSWORD`	Passwort für die Datenbank Verbindung	<>
`SESSION_LIFETIME`	Laufzeit einer Session. Standardmäßig ist es auf 120 Minuten gestellt. Es empfiehlt sich daher eine längere Laufzeit zu wählen	480

Wenn man die Umgebungsvariablen im der docker-compose.yaml anpasst, muss man darauf achten, das die Umgebungsvariablen DB_NAME, DB_USERNAME, DB_PASSWORD sowohl im bookstack, als auch im bookstack-db Service benutzt werden.

Installation und Ersteinrichtung

Starten des Stacks

Nachdem die Einstellungen vorgenommen wurden, kann der Stack mit Hilfe des folgenden Befehls gestartet werden:

docker compose up -d

Anschließend werden die Images heruntergeladen und als Docker Container gestartet werden. Wenn alle Container gestartet sind, ist die Anwendung unter folgender URL erreichbar: http://<<HOSTNAME>>:8080

Erstanmeldung

Nach der Installation kann man sich mit den Standardanmeldedaten anmelden:

User: admin@admin.com
Passwort: password

Es empfiehlt das Passwort des Users direkt zu ändern, bzw. direkt einen neuen Admin User anzumelden und den Account zu deaktivieren. Dazu navigieren wir zu Einstellungen -> Benutzer -> BENUTZER HINZUFÜGEN. Anschließend legen wir einen neuen Benutzer an. Diesere Nutzer sollte als die Rolle Admin bekommen. Da wir aktuell keine Möglichkeit haben dem Nutzer eine Einladungs Mail zu schicken, wählen wir den Haken bei Benutzer-Einladungs-E-Mail schicken ab und vergeben ein Passwort.

Anschließend melden wir uns mit dem neuen Benutzer an und gehen zurück in die Benutzereinstellungen. Dort wählen wir den "alten" Admin Benutzer aus und klicken anschließend auf Benutzer löschen. Um wirklich sicher zu gehen, das wir uns nicht komplett aus dem System aussperren, haben wir nun die Möglichkeit alle bisherigen Beiträge des Benutzers auf einen anderen Benutzer zu übertragen. Wir wählen dazu unseren neu erstellten Admin Benutzer aus und klicken anschließend auf Bestätigen.

Somit haben wir nun die Ersteinrichtung von Bookstack abgeschlossen. In zukünftigen Blog Einträgen werde ich zeigen, wie man Single Sign On, inklusive Rechte und Rollen auf Basis von Keycloak einrichtet und anschließend eine Grundlegende Goverance aufbaut, damit man die Kontrolle über die Bookstack Instanz behält. Dies ist gerade wichtig, wenn man mit vielen Nutzern sich die Bookstack Instanz teilt und gemeinsam an Dokumenten arbeitet.