Bookstack

Diese Seite wird mittels Bookstack bereitgestellt.

Bei Bookstack handelt es sich um eine Web App zum selber hosten, um Bücher zu verwalten. Dabei werden nicht einfach klassisch Bücher als PDFs hochgeladen, sondern online geschrieben und entsprechend interaktiv dargestellt. Es eignet sich sehr gut, um z. B. längere Anleitungen, Anweisungen oder Wissen zu vermitteln. Ein Buch kann aus mehreren Kapiteln mit mehreren Seiten bestehen. Diese werden dann in Regale eingeordnet. Zusätzlich stehen Tags zum Suchen sowie eine Volltext-Suche zur Verfügung, um die gewünschten Informationen zu finden.

Installation & Konfiguration

Einige Einstellungen, die an der Docker Konfiguration vorgenommen werden können, um Bookstack anzupassen, wie Standard-Sprache, -Theme, Reverse Proxy. Eine vollständige Liste mit allen Umgebungsvariablen gibt es hier: https://github.com/BookStackApp/BookStack/blob/92922288dd55ce0f77acc83eea9068cad28dccd9/.env.example.complete#L38

Installation & Konfiguration

Installation

Bookstack kann auf verschiedenen Plattformen installiert werden, siehe hierzu: Bookstack Docs Installation

Hier wird folgend nur die Bereitstellung mittels Docker beschrieben, da diese Instanz ebenfalls mittels Docker gehostet wird.

Bookstack benötigt für die Verwaltung der Daten eine MariaDB als Backend. Somit müssen 2 Container bereitgestellt werden, zum einen ein MariaDB Container und zum anderen der eigentlich Bookstack Container. Sofern schon eine MariaDB Instanz zu Verfügung steht, kann diese eingebunden werden, anstatt einen neuen Container bereitzustellen.

Am einfachsten ist die Bereitstellung mittels Docker Compose. Dazu einfach folgende Compose Datei anpassen:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack
    container_name: bookstack
    environment:
      - APP_URL=http://Server-IP
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=Ein_langes_Passwort
      - DB_DATABASE=bookstackapp
    volumes:
      - ./bookstack_app_data:/config
    ports:
      - 80:80
    restart: unless-stopped
    depends_on:
      - bookstack_db
  bookstack_db:
    image: lscr.io/linuxserver/mariadb
    container_name: bookstack_db
    environment:
      - MYSQL_ROOT_PASSWORD=Noch_ein_extra_langes_Passwort
      - TZ=Europe/Berlin
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=Ein_langes_Passwort
    volumes:
      - ./bookstack_db_data:/config
    restart: unless-stopped

Schauen wir uns noch einige Einstellungen im Detail an.

      - APP_URL=http://Server-IP

Die APP_URL gibt an, wie die Links innerhalb von Bookstack benannt werden sollen. Sollte Bookstack hinter einem Reverse Proxy agieren, ist hier die URL anzugeben, unter der Bookstack von außerhalb erreichbar sein soll. Auch wenn der Reverse Proxy mittels HTTP und unter einem anderen Namen auf den Bookstack Container zugreift, muss mittels der APP_URL die tatsächliche externe HTTPS URL angegeben werden. In diesem Beispiel wird die Server-IP eingegeben, dies ist nur für das lokale testen geeignet und ermöglicht es, dass auch von anderen Geräten innerhalb des selben Netzwerkes auf die URL zugegriffen werden kann. Wenn nur auf der Maschine getestet werden soll, die Bookstack bereitstellt, dann kann auch localhost angegeben werden.

Bereits vorhandene MariaDB verwenden

      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=Ein_langes_Passwort
      - DB_DATABASE=bookstackapp

In diesem Codeabschnitt wird die Verbindung zur MariaDB konfiguriert. Sofern kein bestehender MariaDB-Server verwendet werden soll, muss hier nur das Passwort geändert werden.

Vorsicht: Das Passwort für den Datenbank Benutzer bookstack muss an 2 Stellen angepasst werden. Einmal im gezeigten Code Ausschnitt und bei der Konfiguration des 2. Containers für die MariaDB.

Wenn ein bereits vorhandener MariaDB-Server verwendet werden soll, dann muss auf diesen zuerst die Datenbank bookstackapp angelegt werden sowie der Benutzer bookstack. Diesem Benutzer müssen dann alle Rechte für die neue Datenbank ereilt werden. Anschließend muss mindestens der DB_Host in dem oben gezeigten Codeabschnitt angepasst werden. Außerdem kann der folgende Codeabschnitt aus der Konfiguration gelöscht werden:

    depends_on:
      - bookstack_db
  bookstack_db:
    image: lscr.io/linuxserver/mariadb
    container_name: bookstack_db
    environment:
      - MYSQL_ROOT_PASSWORD=Noch_ein_extra_langes_Passwort
      - TZ=Europe/Berlin
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=Ein_langes_Passwort
    volumes:
      - ./bookstack_db_data:/config
    restart: unless-stopped

Damit die Einstellungen und Daten auch nach dem neu erstellen eines Containers noch vorhanden sind, definiert die Konfiguration 2 Ordner als Volumes. In der Beispiel Konfiguration wird der aktuelle Ordner als Hauptordner verwendet, d. h. in diesem werden folgende Ordner erstellt: bookstack_app_data und bookstack_db_data. Es empfiehlt sich, hier absolute Pfade anzugeben wie: /home/user/bookstack anstelle des "."(Punktes).

Um die Docker Compose Konfiguration auszuführen, kann am besten in das Verzeichnis der YAML Datei gewechselt werden. Danach wird je nach nach gewählter Installation sudo docker-compose up -d oder sudo docker compose up -d (keine Bindestrich zwischen docker und compose) eingegeben, um die Standard Konfiguration docker-compose.yml zu starten. Compose erstellt dann die gewünschten Container mit den angegeben Optionen. Sollten die Container bereits mit dieser Compose Konfiguration erstellt worden sein, so werden die Container in dieser neu erstellt, dessen Konfiguration geändert wurde.

In wenigen Minuten sollte Bookstack unter http://Server-IP erreichbar sein.

Standard-Login:

Installation & Konfiguration

Zeitzone einstellen

Die Zeitzone kann zum einen im Docker Container selbst angepasst werden, sodass die Zeiten im Log des Containers stimmen sowie für die Bookstack App selbst, damit sie auch in Bookstack selbst passend angezeigt werden. Wenn die MariaDB ebenfalls als Container wie in der Installation beschrieben bereitgestellt wird, empfiehlt es sich auch dort die Zeitzone wie in Bookstack einzustellen.

Anpassung der Zeitzone für Bookstack

Um die Zeitzone anzupassen, sind einige Parameter unter environment anzupassen:

  bookstack:
    environment:
      - TZ=Europe/Berlin
      - APP_TIMEZONE=Europe/Berlin

TZ setzt die Zeitzone im Container selbst, sodass die Logs im Container nun in der Zeitzone Europe/Berlin geschrieben werden. APP_TIMEZONE setzt die Zeitzone für Bookstack, sodass alle Zeiten in Bookstack ebenfalls die selbe Zeitzone verwenden. Die beiden Parameter können einfach zu den bereits vorhandenen environment Parametern in Docker Config für den Service bookstack hinzugefügt werden.

Anpassung der Zeitzone für MariaDB

Um die Zeitzone für den MariaDB Container anzupassen ist dem environment Bereich vom Service bookstack_db der Parameter TZ hinzufügen.

  bookstack_db:
    environment:
      - TZ=Europe/Berlin

Zum Schluss nochmal sudo docker-compose up -d oder sudo  docker compose up -d ausführen, um die Container neu erstellen zu lassen.

Installation & Konfiguration

Bookstack & DB nicht als root

Im Standard werden die Container als Systemuser root ausgeführt. Dies gilt als Risiko, da ein Ausbruch aus dem Container dazu führt, dass der Angreifer mit root Rechten auf dem Host agieren kann. Um dies zu verhindern, können die Dienste in den Containern mit einem anderen Benutzer ausgeführt werden. Hierzu kann die Docker Config aus der Installation angepasst werden.

  bookstack:
    environment:
      - PUID=1000
      - PGID=1000

Die beiden neuen Parameter (PUID und PGID) werden einfach unter die bereits vorhandenen Parameter in environment geschrieben. Sie haben zur Folge, dass die Dienste dann als User mit der ID 1000 und der Gruppen ID 1000 laufen, die IDs sind wichtig und müssen bei den Anpassungen der Berechtigungen berücksichtigt werden.

Durch die Anpassung des Dienst-Benutzers, kann dieser natürlich nicht mehr auf die bereits vorhandenen Dateien zugreifen. Deswegen müssen die Berechtigungen/Eigentümer der Verzeichnisse, die in der Docker Config angegeben sind, geändert werden.
Dazu kann der folgende Befehl angepasst und verwendet werden: sudo chown -R 1000 ./bookstack_app_data

Sofern auch die MariaDB als Container wie in der Installation beschrieben eingerichtet wurde, kann der Dienst-Benutzer auf die selbe Art angepasst werden.

  bookstack_db:
    environment:
      - PUID=1000
      - PGID=1000

Nachdem die Config angepasst ist, kann der Container mit sudo docker-compose up -d neu erstellt werden, um die Änderungen anzuwenden.

Installation & Konfiguration

Standard-Design anpassen

Bookstack erlaubt das Überschreiben einiger Standard-Einstellungen für die Seite. So kann z. B. standardmäßig der essentielle Dark Mode aktiviert, die Ansicht von Büchern und Regalen auf Liste und die Standard-Sprache (sofern nicht vom Browser erkannt) umgestellt werden. Es gibt noch viele weitere Einstellungen, die in der offiziellen Dokumentation nachzulesen sind: https://github.com/BookStackApp/BookStack/blob/92922288dd55ce0f77acc83eea9068cad28dccd9/.env.example.complete#L38

Um die Einstellungen vorzunehmen, kann eine .env Datei angelegt und gepflegt werden oder es wird die bereits vorhandene Docker Config aus der Installation angepasst. Dazu werden einfach die gewünschten Parameter im Bereich environment hinzugefügt.

Im folgenden werden folgende Standard-Einstellungen vorgenommen:

  bookstack:
    environment:
      - APP_LANG=de  
      - APP_DEFAULT_DARK_MODE=true
      - APP_VIEWS_BOOKS=list
      - APP_VIEWS_BOOKSHELVES=list

Zum Schluss nochmal sudo docker-compose up -d oder sudo  docker compose up -d ausführen, um die Container neu erstellen zu lassen. Anschließend erhalten Gäste die neuen Standards, registrierte Benutzer können diese einfach überschreiben, indem sie eigene Einstellungen für die Sichten in der Weboberfläche vornehmen.

Installation & Konfiguration

Bockstack hinter Reverse Proxy

Bookstack hinter einem Reverse Proxy betreiben. Es müssen nicht zwingend Einstellungen an Bookstack vorgenommen werden, um es hinter einem Reverse Proxy zu betrieben. Im Reverse Proxy kann einfach die Konfiguration angepasst werden, sodass dieser Bookstack als Backend ansteuert und im Frontend anbietet. Um jedoch einen sicheren Betrieb sicherzustellen, sollten einige Anpassungen vorgenommen werden.

  bookstack:
    environment:
      - APP_URL=https://beispiel.de
      - APP_PROXIES=*
      - LOG_FAILED_LOGIN_MESSAGE=true

Installation & Konfiguration

.env Konfigurationsdatei

In der Konfigurationsdatei .env speichert Bookstack alle Standard- und Server-Einstellungen. Darunter auch die Einstellungen, die über die evironment-Variablen in der Docker Compose Datei festgelegt wurden.

Die Datei .env wird automatisch erstellt, wenn der Bookstack Container einmal erzeugt und gestartet wird. Anschließend befindet sich im Ordner, der in der Compose Datei zum Speichern der Bookstack Konfiguration festgelegt ist (./bookstack_app_data:/config), der Ordner www.

Angenommen es würde zum Beispiel folgendes Volume für den Bookstack Container in der Compose Datei definiert.

services:
  bookstack:
    volumes:
      - /home/user/docker/bookstack_app_data:/config

Dann würde in diesem Fall die Konfigurationsdatei wie folgt abgelegt: /home/user/docker/bookstack_app_data/www/.env.

Die Datei kann so bearbeitet werden. Nach der Bearbeitung wird einfach der Container neugestartet und die Änderungen sind direkt angewendet.

In der Datei können zusätzliche Einstellungen vorgenommen werden. Eine vollständige Liste: Umfangreiches .env Beispiel

Installation & Konfiguration

Ausgehende E-Mails

Um automatisch Benachrichtigungen versenden zu können, wie z. B. bei Kommentaren oder beobachteten Seiten, ist ein SMTP-Server samt Postfach in Bookstack zu hinterlegen. Hierzu ist die .env Konfigurationsdatei anzupassen.

.env Konfigurationsdatei

In der Konfigurationsdatei .env speichert Bookstack alle Standard- und Server-Einstellungen. Darunter auch die Einstellungen, die über die evironment-Variablen in der Docker Compose Datei festgelegt wurden.

Die Datei .env wird automatisch erstellt, wenn der Bookstack Container einmal erzeugt und gestartet wird. Anschließend befindet sich im Ordner, der in der Compose Datei zum Speichern der Bookstack Konfiguration festgelegt ist (./bookstack_app_data:/config), der Ordner www.

Angenommen es würde zum Beispiel folgendes Volume für den Bookstack Container in der Compose Datei definiert.

services:
  bookstack:
    volumes:
      - /home/user/docker/bookstack_app_data:/config

Dann würde in diesem Fall die Konfigurationsdatei wie folgt abgelegt: /home/user/docker/bookstack_app_data/www/.env.

Die Datei kann so bearbeitet werden. Nach der Bearbeitung wird einfach der Container neugestartet und die Änderungen sind direkt angewendet.

In der Datei können zusätzliche Einstellungen vorgenommen werden. Eine vollständige Liste: Umfangreiches .env Beispiel

In dieser Datei sind folgende Optionen zu ergänzen.

# Mail system to use
# Can be 'smtp' or 'sendmail'
MAIL_DRIVER=smtp

# Mail sender details
MAIL_FROM_NAME="Bookstack Postach"
MAIL_FROM=bookstack@beispiel.de

# SMTP mail options
# These settings can be checked using the "Send a Test Email"
# feature found in the "Settings > Maintenance" area of the system.
# For more detailed documentation on mail options, refer to:
# https://www.bookstackapp.com/docs/admin/email-webhooks/#email-configuration
MAIL_HOST=smtp.beispiel.de
MAIL_PORT=587
MAIL_USERNAME=bookstack@beispiel.de
MAIL_PASSWORD=SuperSicheresLangesPasswort
MAIL_ENCRYPTION=tls

# Folgende Option ist ein Sicherheitsrisiko
#MAIL_VERIFY_SSL=false

Danach den Container neustarten und fertig.

Installation & Konfiguration

LDAP/AD Synchronisation

Statt der "normalen" Authentifizierung kann auch z. B. ein LDAP als Authentifizierung verwendet werden. Dann können sich die Benutzer im LDAP mit den gleichen Anmeldedaten in Bookstack anmelden und sogar die Gruppen können synchronisiert und für Rollenzuteilungen verwendet werden.

AD/LDAP Synchronisation: https://www.bookstackapp.com/docs/admin/ldap-auth/

Die in der Dokumentation beschriebenen Einstellungen über die .env Datei setzen, nicht die Environment Variablen in der Docker Compose verwenden.

.env Konfigurationsdatei

In der Konfigurationsdatei .env speichert Bookstack alle Standard- und Server-Einstellungen. Darunter auch die Einstellungen, die über die evironment-Variablen in der Docker Compose Datei festgelegt wurden.

Die Datei .env wird automatisch erstellt, wenn der Bookstack Container einmal erzeugt und gestartet wird. Anschließend befindet sich im Ordner, der in der Compose Datei zum Speichern der Bookstack Konfiguration festgelegt ist (./bookstack_app_data:/config), der Ordner www.

Angenommen es würde zum Beispiel folgendes Volume für den Bookstack Container in der Compose Datei definiert.

services:
  bookstack:
    volumes:
      - /home/user/docker/bookstack_app_data:/config

Dann würde in diesem Fall die Konfigurationsdatei wie folgt abgelegt: /home/user/docker/bookstack_app_data/www/.env.

Die Datei kann so bearbeitet werden. Nach der Bearbeitung wird einfach der Container neugestartet und die Änderungen sind direkt angewendet.

In der Datei können zusätzliche Einstellungen vorgenommen werden. Eine vollständige Liste: Umfangreiches .env Beispiel

Installation & Konfiguration

Cache & Session Konfiguration

Über .env Datei lassen sich der Cache und die Verarbeitung der Sessions (Sitzungen) anpassen.

.env Konfigurationsdatei

In der Konfigurationsdatei .env speichert Bookstack alle Standard- und Server-Einstellungen. Darunter auch die Einstellungen, die über die evironment-Variablen in der Docker Compose Datei festgelegt wurden.

Die Datei .env wird automatisch erstellt, wenn der Bookstack Container einmal erzeugt und gestartet wird. Anschließend befindet sich im Ordner, der in der Compose Datei zum Speichern der Bookstack Konfiguration festgelegt ist (./bookstack_app_data:/config), der Ordner www.

Angenommen es würde zum Beispiel folgendes Volume für den Bookstack Container in der Compose Datei definiert.

services:
  bookstack:
    volumes:
      - /home/user/docker/bookstack_app_data:/config

Dann würde in diesem Fall die Konfigurationsdatei wie folgt abgelegt: /home/user/docker/bookstack_app_data/www/.env.

Die Datei kann so bearbeitet werden. Nach der Bearbeitung wird einfach der Container neugestartet und die Änderungen sind direkt angewendet.

In der Datei können zusätzliche Einstellungen vorgenommen werden. Eine vollständige Liste: Umfangreiches .env Beispiel

 

Cache & Sitzungsspeicher

In der Standard Einstellung nutzt Bookstack das lokale Dateisystem als Cache. Darin sind neben dem Cache auch die Sitzungsdaten der Benutzer gespeichert. Um die Performance zu verbessern, können andere Systeme anstelle des lokalen Dateisystems verwendet werden, welche im folgenden vorgestellt werden.

Datenbank

Die am einfachsten einzurichtende Alternative ist das Speichern des Caches in der bereits für die Daten genutzten Datenbank. Dazu reicht es die folgenden beiden Zeilen in der .env Datei zu ergänzen und den Container neuzustarten.

CACHE_DRIVER=database
SESSION_DRIVER=database

Memcached

Um Memcached als Cache nutzen zu können, muss natürlich ein Memcached-Server vorhanden sein, der von Bookstack genutzt werden kann. Sobald ein solcher Server bereit steht, kann die .env Konfiguration angepasst werden.

CACHE_DRIVER=memcached
SESSION_DRIVER=memcached
MEMCACHED_SERVERS=127.0.0.1:11211:100

Neu ist nun die 3. Zeile, in der der Memcached Server zu definieren ist. Die localhost-IP ist dann durch die richtige IP oder den Hostname auszutauschen. Es können auch mehrere Server angegeben werden. Dabei spielt die Zahl hinter dem letzten Doppelpunkt eine entscheidende Rolle, die gibt die Gewichtung des Servers an.

Da Memcached nur Daten im Arbeitsspeicher zwischenspeichert, muss fast nichts konfiguriert werden, um einen Server bereitzustellen. Die folgende minimale Docker Compose Konfiguration reicht völlig aus, um einen Cache Server bereitzustellen.

services:
  memcached:
    image: memcached
    container_name: memcached
    restart: unless-stopped

Der Dienst memcached kann nun in eine beliebige andere Compose Konfiguration kopiert werden, um dort als Cache zu dienen. Dann nur noch bei den anderen Diensten den Servernamen hinterlegen und fertig.

Redis

Im Prinzip erfolgt die Konfiguration genauso wie bei Memcached. Nur das die Zahl nach dem letzten Doppelpunkt nun nicht die Gewichtung, sondern die Datenbank angibt.

CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_SERVERS=127.0.0.1:6379:0

Die Cookies werden zum Verfolgen der Sitzungen in Bookstack genutzt. Hier werden 2 Anpassungsmöglichkeiten angeboten.

# Only send cookies over a HTTPS connection.
# Ensure you have BookStack served over HTTPS before enabling.
# Defaults to 'false'
SESSION_SECURE_COOKIE=true
# Set the name of the cookie used by BookStack to track sessions.
# Defaults to 'bookstack_session'
SESSION_COOKIE_NAME=custom_cookie_name

Session Timeouts

Im Standard wird ein Benutzer nach 2 Stunden Inaktivität automatisch ausgeloggt. Diese Zeitspanne kann ebenfalls in der .env angepasst werden.

# Session lifetime in minutes.
# Defaults to 120
SESSION_LIFETIME=240

Aufbau von Bookstack

Auf dieser Seite geht es um den Aufbau von Bookstack, da sich hieraus das Speichern und Auffinden der Inhalte ergibt. Begonnen wird mit der größten Einheit, einem Regal und geht bis zur kleinsten Einheit einer Seite. Letztlich ist Bookstack wie eine digitale Bibliothek aufgebaut.

Regale

Die Regale repräsentieren die Bücherregale einer Bibliothek. Mit diesem werden verschiedene Bücher logisch zusammengefasst und geordnet. Jedoch hat Bookstack eine Besonderheit, denn ein Buch kann nicht nur in einem Regal stehen, sondern in mehreren Regalen. So können beispielsweise Bücher mit Grundlagenwissen zu SQL sowohl in dem Regal IT-Basiswissen sowie in Datenbanken stehen. Dadurch wird das Auffinden der passenden Bücher einfacher, wenn ein Benutzer gerne in den Regalen stöbert, um z. B. etwas über Datenbanken zu erfahren ohne konkret nach SQL zu suchen. Zusätzlich können Regale noch mit Tags versehen werden, wodurch auch bei vielen Regalen die passenden gut auffindbar sind. Jedes Regal hat eine Beschreibung, um den Benutzern kurz die zu erwartenden Inhalte zu erklären.

Bücher

Ein Buch ist die neben einer Seite die wichtigste Einheit in Bookstack. Es hält letztlich die Informationen zusammen, die zusammen gehören. Ein Buch kann in keinem, einem oder mehreren Regalen stehen. Wobei versucht werden sollte, ein Buch wenigstens einem Regal zuzuordnen, um die Informationen auch den Benutzern zugänglich zu machen, die ggf. nur über die Regale arbeiten. Zusätzlich kann ein Buch auch ein oder mehrere Tags erhalten, wodurch ein Benutzer auch gezielt nach passenden Inhalten suchen kann ohne die Regale zu berücksichtigen. Jedes Buch hat eine Beschreibung, um den Benutzern kurz die zu erwartenden Inhalte zu erklären.

Kapitel

Kapitel sind wie Regale optional und müssen nicht verwendet werden. Es kann dabei helfen, wenn ein Buch viele Seiten enthält, diese besser zu strukturieren. Auch Kapitel können wieder mit Tags versehen werden, sodass diese auch unabhängig von den Büchern gefunden zu werden. Ein Kapitel verfügt ebenfalls über eine Beschreibung, um wieder kurz den Inhalt zu erläutern.

Seiten

Dies ist die kleinste Einheit, die letztlich die Informationen beinhaltet. Der Anfangstext der Seite wird im Kapitelverzeichnis mit angezeigt. Jede Seite kann wieder mit Tags versehen werden, um auch die Seiten unabhängig von den Büchern/Kapiteln wiederfinden zu können. Eine Seite kann völlig frei aufgebaut werden, Überschriften, Abschnitte, farbliche Hervorhebungen, Codeabschnitte, Tabellen, Grafiken, Medien, usw.

Tags

An dieser Stelle werden nochmals kurz die Tags aufgenommen, da diese bei allen Einheiten zum Einsatz kommen. Wird nach einem Tag gesucht, der sowohl bei einem Buch, bei einem Kapitel und einer Seite gesetzt ist, so werden alle Einheiten angezeigt. So lassen sich Informationen unabhängig von den Strukturen finden. Gleichzeitig sollte also vor allem bei Regalen oder Büchern (sofern diese einen großen Umfang haben) vorsichtig mit den Tags umgegangen werden. Denn Wenn jedem Regal alle Tags der Bücher zugewiesen werden, taucht bei jedem Tag auch das Regal auf, obwohl der Benutzer eigentlich die Bücher/Kapitel/Seiten gezielt ansteuern möchte. So wird die Suche ggf. unnötig komplex, da der Benutzer die Regale extra ausblenden muss.

Arbeiten mit Bookstack

Vorstellung der Bearbeitung von Kapiteln, Büchern, Seiten und Inhalten in Bookstack. Einbetten von Inhalten in andere Seiten, Querverweise usw.

Arbeiten mit Bookstack

Inhalte aus anderen Seiten

Die Inhalte aus anderen Seiten lassen sich zum einen als Verweise eingeben oder auch einbetten, um z. B. Textblöcke oder sogar ganze Seiten in eine andere Seite einzubetten.

Verweise

Einbetten

Der Vorteil beim Einbetten von Absätzen anderer Seiten oder ganzer Seiten ist, dass die Inhalte nur an der Quelle anzupassen sind und automatisch an allen referenzierten Stellen aktuell dargestellt werden. So können Textpassagen, die häufiger verwendet werden, immer wieder referenziert werden und sind trotzdem leicht anzupassen.

Bookstack bietet hierzu selbst eine Anleitung in der offiziellen Dokumentation: https://www.bookstackapp.com/docs/user/reusing-page-content/

Als Beispiel wird folgend aus dem Buch Docker von der Seite Compose ein Abschnitt eingebunden (Die Quelle wird nicht mit angegeben, diese wurde hier manuell ergänzt):

Alle Optionen sollten bereits vom docker run bekannt sein, auch das Image wurde dort verwendet, nur das es nicht expliziert als Image bezeichnet wurde (sudo docker run --name test -d lscr.io/linuxserver/bookstack).

Quelle: https://jaeckel.one/link/48#bkmrk-alle-optionen-sollte

Der Code hierfür lässt sich einfach erzeugen. Dazu zu der gewünschten Seite wechseln und doppelt auf den Abschnitt bzw. eines der Worte in dem Abschnitt klicken, der eingebunden werden soll. Es wird ein kleines Pop-Up geöffnet, welches einen Permalink zum Abschnitt anzeigt, dort gibt es rechts ein kleines Symbol, beim Klick wechselt der Link, sodass anstelle des normalen Permalinks der Code zum Einbetten angezeigt wird.

image.png

Arbeiten mit Bookstack

Berechtigungen

Im Standard ist das Rechteschema von Bookstack einfach gehalten, jedoch lässt es sich mit Rollen und Benutzern bis auf Seitenebene erweitern. Es können Berechtigungen für Regale, Bücher, Kapitel und Seiten vergeben werden. Außerdem lässt sich in den Grundlagen festlegen, ob generell die gesamte Instanz öffentlich ist oder nicht.

Öffentlicher Zugriff

Eine grundlegende Einstellung ermöglicht es die gesamte Instanz generell freizugeben. So ist z. B. diese Bookstack Instanz öffentlich, sodass auch Gäste ohne Login die Informationen einsehen können.

Um eine Instanz öffentlich verfügbar zu machen, kann ein Admin in den Einstellungen unter Funktionen & Sicherheit den öffentlichen Zugriff aktivieren, wie im folgenden Screenshot zu sehen.

grafik.png

Hierdurch sind nun standardmäßig alle Bücher für alle Besucher lesbar. Außer die Berechtigungen werden explizit entzogen oder die Rolle des Gastes angepasst.

Rollen

Nach der Installation von Bookstack stehen 4 Benutzer-Rollen zu Auswahl. Über die Rollen werden diverse Berechtigungen gesteuert, wie z. B. wer Bücher erstellen und bearbeiten darf. Die Rollenverwaltung kann als Admin in den Einstellungen unter Rollen eingesehen und angepasst werden. Es können sowohl neue Rollen erstellt als auch bestehende Rollen angepasst werden.

grafik.png

Generell gilt für die Vererbung der Berechtigungen, dass die Standard-Rollen angewendet werden. Diese müssen explizit durch eigene Berechtigungen überschrieben werden und zwar jede Rolle einzeln. Nehmen wir mal das Beispiel, dass es ein Buch mit diversen Hinweisen für Admins gefüllt ist und nur für diese sichtbar sein soll. Dann müssen die Rollen Editor, Public und Viewer überschrieben werden, indem ihnen für dieses Buch alle Rechte explizit entzogen werden.

Rollen stellen die Standardberechtigungen für Regale, Bücher, Kapitel und Seiten dar. Sie gelten immer, solange diese nicht explizit in den Berechtigungen für die genannten Objekte überschrieben werden. Wie das funktioniert, beschreibt der folgende Abschnitt.

Berechtigungen für Bücher/Kapitel/Seiten

Wie im vorherigen Abschnitt beschrieben gelten die Berechtigungen der Rollen für alle Bücher, Kapitel und Seiten sowie Regale. Da Regale eine besondere Rolle bei der Vererbung der Rechte aufweisen, werden diese im nächsten Abschnitt (Berechtigungen für Regale) getrennt betrachtet.

Generell gilt: Ein Buch vererbt die überschriebenen Rollen an seine Kapitel und Seiten. Nur wenn ein Kapitel wiederum Rollen überschreibt, werden die Rollen der Seite überschrieben und an die Seiten des Kapitels vererbt. Eine Seite wiederum kann selbst die Rollen des Buchs oder Kapitels überschreiben und eigene Berechtigungen aufweisen.

Im folgenden Beispiel werden die Berechtigungen für das Buch Bookstack angepasst. Dieses soll nur für Admins und Editoren sichtbar sein. Außerdem sollen nur die Admins dieses Buch bearbeiten dürfen. Zuerst öffnen wir das Buch und rufen die Berechtigungen auf.

grafik.png

Hier sehen wir nun die aktuellen Berechtigungen. Es gelten die Standard-Rollen bzw. Standardeinstellungen.

grafik.png

Überschreiben wir zuerst die Berechtigung für die Autoren, welche das Buch nur lesen sollen und nicht bearbeiten dürfen. Dazu zuerst die zu überschreibende Rolle auswählen, wie im folgenden Screenshot zu sehen.

grafik.png

Daraufhin wird eine neue Zeile hinzugefügt. Diese zeigt die Rolle an und welche Rechte diese für das aktuelle Buch hat. Sofern nichts angeklickt wird, verliert sie alle Rechte. Wir setzen nun einen Haken bei Anzeigen und wählen Berechtigung speichern.

grafik.png

Für die beiden Rollen Public und Viewer werden die Schritte nochmals ausgeführt, aber es werden keine Haken gesetzt. Dadurch verlieren diese beiden Rollen jeglichen Zugriff auf das Buch. Die Rechte sehen nun wie folgt aus.

grafik.png

Um die Standardrechte für eine Rolle wiederherzustellen, kann die Überschreibung einfach mit einem Klick auf das X am Ende der Zeile angeklickt werden, wodurch diese gelöscht wird.

Berechtigungen für Regale

Die Berechtigungen für Regale sind besonders, da diese nicht vererbt werden. Dies wäre ein Problem, da ein Buch in mehrere Regale "gestellt" werden kann. Wenn diese Regale nun unterschiedliche Berechtigungen setzen würden, wäre es nicht möglich, die Berechtigungen des Buches zu setzen.

Jedoch bietet das Menü für die Berechtigungen der Regale die Option, die Regalberechtigungen einmalig auf alle Bücher im Regal anzuwenden und die ggf. vorhandenen Berechtigungen zu überschreiben: Kopiere die Berechtigungen zum Buch

grafik.png

Arbeiten mit Bookstack

Seiten bearbeiten

Bookstack bietet 2 verschiedene Editoren für die Bearbeitung der Seiten an.

Standardmäßig ist der WYSIWYG Editor aktiv. Dieser funktioniert ähnlich wie Word, es werden Formatierungen angewendet und diese direkt angezeigt. Somit ist dieser Editor der "leichtere" insbesondere für technisch weniger versierte Benutzer.

Neben dem WYSIWYG Editor kann auch ein Markdown Editor verwendet werden. Dieser zeichnet sich durch eine schnellere und präzisere Bearbeitung aus, da die Formatierungsoptionen angezeigt werden, nicht wie es später aussieht. Dafür muss ein kleines Set an Befehlen erlernt werden. Neben der effizienteren Bearbeitung bietet es auch einen schönen Komfort: Notizen z. B. aus Obsidian oder Logseq direkt zu kopieren, inklusive der Formatierungen. Dies ist möglich, da beide Notizbücher ebenfalls in Markdown verfassen.

Der Editor kann auch für bereits gefüllte Seiten geändert werden. Jedoch besteht hierbei die Gefahr, dass Formatierungen verloren gehen, da insbesondere Markdown nicht alle Formatierungen vom WYSIWYG Editor unterstützt.

Tastenkürzel

Unabhängig vom Editor können Tastenkürzel verwendet werden. Diese variieren jedoch ein wenig. Es lohnt sich das eine oder andere Kürzel zu lernen, da diese das Schreiben von Inhalten enorm beschleunigen und für einige Funktionen auch vereinfachen. Die vollständige Dokumentation für die Editoren finden sich hier: WYSIWYG Tastenkürzel und Markdown Tastenkürzel.

Eine Funktion die durch die Tastenkürzel enorm vereinfacht wird, ist das Verlinken von anderen Büchern und Seiten. Statt den gewünschten Inhalt in einem 2. Fenster zu öffnen und den Link zu kopieren, kann einfach STRG+Shift+K gedrückt werden. Dann wird folgender Dialog geöffnet, welcher die Auswahl des Buchs bzw. der Seite ermöglicht.

grafik.png

Skizzen erstellen

Es können nicht nur Grafiken in Bookstack eingefügt werden. Mit Draw.io steht eine Integration bereit, welche das direkte Erstellen von Grafiken und Skizzen aus Bookstack heraus ermöglicht. Der Grafikdesigner wird durch einen Klick auf den unten gezeigten Menüeintrag geöffnet. Diese Integration steht auch im Markdown Editor zur Verfügung.

grafik.png

Nun wird der Grafikdesigner von Draw.io angezeigt, welcher eine große Anzahl an Symbolen zur Verfügung steht, um Prozesse, Systeme, Gebäude und vieles mehr anschaulich darstellen zu können.

grafik.png

Sobald die Grafik entworfen wurde, reicht ein Klick auf speichern, um die Grafik direkt in Bookstack als Skizze zu hinterlegen und automatisch in den Editor einfügen zu lassen.

grafik.png

Editoren im Detail

WYSIWYG

Die Vorteile dieses Editors sind seine einfache Bedienung und ein großer Umfang an Formatierungsoptionen. Auch wenn der Markdown Editor besser zum Austausch von reinem Markdown geeignet ist, so ist der WYSIWYG Editor ebenfalls in der Lage, Formatierungen beim Kopieren beizubehalten.

Ansonsten gibt es nicht viel zum Editor zu erzählen, denn die Bedienung ist ähnlich wie bei Word. Oben befindet sich eine Menüleiste mit den Formatierungsoptionen und rechts befindet sich ein Menü für Schlagwörter, Anhänge usw.

grafik.png

Markdown

Insbesondere im Zusammenspiel mit Notizbüchern wie Obsidian oder Logseq bietet dieser Editor hervorragende Kopiermöglichkeiten. Es können zum einen Inhalte aus den Notizbüchern direkt in den Markdown Editor von Bookstack kopiert werden, dabei bleiben alle Formatierungen erhalten. Zum anderen können auch die Inhalte aus den Büchern direkt in Obsidian oder Logseq kopiert werden, auch hier bleiben die Formatierungen erhalten, dank Markdown.

Normalerweise ist in Bookstack der WYSIWYG Editor aktiviert. Um für eine Seite den Editor zu ändern, oben in der Menüleiste auf Entwurf klicken und eine der beiden Markdown Umwandlungen auswählen.

grafik.png

Sauberer Inhalt: Blankes Markdown, bietet die bestmögliche Kompatibilität zu anderen Markdown Tools, es  stehen jedoch deutlich weniger Formatierungen zur Auswahl, was insbesondere bei bereits vorhandenen Inhalten zu Verlusten führen kann.
Stabiler Inhalt: Um HTML erweitertes Markdown, bietet weniger Kompatibilität zu anderen Markdown Tools, dafür stehen mehr Formatierungsoptionen zur Auswahl und bei einem Wechsel gehen deutlich weniger Formatierungen verloren.

Egal welche der beiden Optionen gewählt wird, vor dem Wechsel erscheint eine Sicherheitsabfrage mit einigen Hinweisen.

grafik.png

Nachdem auf Weiter geklickt wurde, sieht der Editor nun wie folgt aus.

grafik.png

Auf der linken Seite wird der Markdown Editor angezeigt und rechts die Vorschau. Hier ist zu sehen, dass die im Text hinterlegte Warnbox erhalten geblieben ist sowie die Überschrift.

Natürlich kann auch jederzeit wieder zum anderen Editor gewechselt werden, dazu einfach wieder über Entwurf den Editor wechseln.

grafik.png

Auch im Markdown Editor stehen Funktionen zum Einfügen von Bildern und zum Erstellen von Grafiken mit Draw.io zur Auswahl sowie Anhänge und Schlagwörter.

grafik.png