Eigene BookStack-Instanz installieren

ℹ️ DieserDiese ArtikelAnleitung erklärtstartet erst ab dem Punkt,Punkt, woan mandem schondu bereits einen Linux-Server aufgesetzt hathast und auch Docker schon installiert ist. Die „Schritte davor“ folgen später – Ich werde demnächst alle vorangegangenen Schritte erklären,es ist wirklich nicht schwer,schwer vor Allem(besonders mit Hilfe von KIs.​KI-Hilfe).

---

SchrittÜberblick: 1:Was Kompositionwird vorbereitenhier eingerichtet?

WirDu wollen,bekommst dassam eineEnde:

Domain

eingerichtetBookStack wird,(Wiki/Docs-System) dieMariaDB als Datenbank Caddy als Reverse Proxy mit https://...automatischem aufgerufenHTTPS werden(Let’s kann,Encrypt) weshalb🌐 ich mich

---

für Caddy entschieden habe.

ℹ️

Hintergrund: Was ist Caddy? 🌐

Caddy ist ein moderner,moderner Webserver (ähnlich Nginx/Apache), geschrieben in Go geschriebener Webserver (ähnlich wie Nginx oder Apache), der besonders„Security-by-default“ dafür bekannt ist, viele Dinge standardmäßig sicherlebt und bequemdir vor allem HTTPS zuextrem machen.bequem macht.

Kernidee: „Webserver, der einfach funktioniert“ ✅

Caddy nimmt dir viel Konfigurationsarbeit ab – vor allem rund um HTTPS.

Wichtige Merkmale ✨

1. Automatisches HTTPS (TLS)
   • CaddyZertifikate kann Zertifikatewerden automatisch beziehenbezogen und erneuernerneuert (typischerweisetypisch via Let’s Encrypt), sodass deine Websites ohne großen Aufwand über https:// laufen..
2. Einfache Konfiguration
   • MitÜber demein gut lesbares Caddyfile (eine schlanke, gut lesbare Konfigurationsdatei) lässt sich vieles sehr kompakt definieren..
3. Reverse Proxy & Load Balancing
   • Ideal, um Anfragen an andereServices Dienste weiterzuleiten, (z. B. anDocker-Container) eine Node.js-, Python- oder Docker-Anwendung.weiterzuleiten.
4. Gute Defaults & Security-by-Default
   • Viele sinnvolle EinstellungenSecurity-Standards sind bereitsdirekt „von Haus aus“ aktiv, statt alles manuell „zusammenschrauben“ zu müssen.aktiv.
5. ErweiterbarModular über Moduleerweiterbar
   • CaddyBei ist modular aufgebaut und kann für speziellespeziellen Anforderungen erweitertlässt werden.sich Caddy ausbauen.

---

Typische Einsatzfälle 🧩

• Websites hosten (statisch oder statisch/dynamisch)
• Reverse Proxy vor einer App (z. B. /api → Backend)
• TLS-Termination und sichere Weiterleitung
• Lokale EntwicklungsumgebungenDev-Setups mit HTTPS

---

Schritt 1: Verzeichnis & Dateien vorbereiten 🧱

Erstelle einendas OrdnerVerzeichnis:

hier:

• /opt/bookstack

Und

Lege darin zwei Dateien:Dateien Caddyfilean:

und

• docker-compose.yml
  

FügeCaddyfile dort den

folgenden

✍️ InhaltWichtig: Du musst gleich ein undpaar passeWerte ihnanpassen an– (du siehst schonim wo^^):YAML sehr deutlich, wo.

BookStack-YML

---

Schritt 2: Docker Compose konfigurieren (docker-compose.yml) 🐳

Füge folgenden Inhalt ein (und passe ihn an, wo nötig):

services:
  mariadb:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack-mariadb
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Berlin
      - MYSQL_ROOT_PASSWORD=PW_OF_MYSQL_ROOT
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=PW_OF_MYSQL_DB
    volumes:
      - ./mariadb:/config
    restart: unless-stopped

  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    depends_on:
      - mariadb
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Berlin

      - APP_URL=https://wiki.fabula.vision
      # Wo wird BookStack aufrufbar sein? (Deine URL)
      - APP_KEY=base64:...
      # Zum Generieren das ausführen: docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
      - APP_THEME=custom
      #'custom' ermöglich es Hacks zu nutzen; mehr dazu hier: https://www.bookstackapp.com/hacks/applying/

      - DB_HOST=mariadb
      - DB_PORT=3306
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=PW_OF_MYSQL_DB
      # (Wie oben!)

      - APP_DEFAULT_DARK_MODE=true
      # (Geschmackssache)

    volumes:
      - ./bookstack:/config
    restart: unless-stopped

  caddy:
    image: caddy:latest
    container_name: caddy
    depends_on:
      - bookstack
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy/data:/data
      - ./caddy/config:/config
    restart: unless-stopped

Schritt 3: Caddy konfigurieren (Caddyfile

) 🛡️

Füge Folgendes ein und ersetze die Domain:

wiki.fabula.vision {
	# Deine URL natürlich...
	encode zstd gzip

	# Reverse Proxy zu BookStack (Container heißt "bookstack", interner Port 80)
	reverse_proxy bookstack:80

	# sinnvolle Header (optional)
	header {
		# HSTS (nur setzen, wenn du sicher bist, dass HTTPS dauerhaft aktiv sein soll)
		Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "strict-origin-when-cross-origin"
	}
}

---

Schritt 2:4: StartenContainer starten ▶️

1. Ins Verzeichnis wechseln:
   
2. cd /opt/bookstack/

Unser Zeugs

Stack installieren:
starten:

docker

compose up -d
Aktualisieren geht dann so:
docker compose pull; docker compose up -d

Aktualisieren geht später so:

Fertig,docker abercompose nunpull docker compose up -d

Fertig ✅
Jetzt schnell die URL aufrufen und die Standard-Zugangsdaten ändern!

Standard-Login (User + Passwort):Login: admin@admin.com +Standard-Passwort: password

Cron

---

Einen

Schritt 5: Cron-Job für BookStack anlegen⏱️

geht

Einen folgendermaßen:Cron-Job anlegen:

Crontab öffnen:

• crontab -e

EintragenFolgende Zeile eintragen (Cron jede Minute):

* * * * * docker exec -i bookstack php /app/www/artisan schedule:run >/dev/null 2>&1

Beschränkungen & Module/Hacks

 🧩

Es gibt drei Einschränkungen, die ich bisher festgestelltaufgefallen habe:sind:

1. E-Mail-Versand
2. (z. B. „Passwort vergessen“) funktioniert nicht,bei mir nicht bzw. meine Experimente haben noch keine Lösung hervorgebrachthervorgebracht.

und ichIch brauche das auches nicht zwingend.zwingend Aber– wenn manaber z. B. für Kommentare aktivieren will (User bekommen eine Benachrichtigung, wenn ihre Seiten kommentiert werden), dannBenachrichtigungen) kommt man dadaran nicht drumherum.vorbei. Mehr dazudazu:
hierhttps://www.bookstackapp.com/docs/admin/email-webhooks/#email-configuration.

ManErweiterung über „Hacks“

BookStack kann dieüber Funktionalität mit sogenanntensogenannte „Hacks"Hacks“ erweiternerweitert undwerden. ichZwei kann zwei Hacks schon mal empfehlen:Empfehlungen:

MathJax/TeX (Mathe-Formeln):

• https://www.bookstackapp.com/hacks/mathjax-tex/
  

Mathe-Formeln darstellen; Mermaid Viewer (Diagramme):

• https://www.bookstackapp.com/hacks/mermaid-viewer/
  

(Mermaid-)Diagramme darstellen;

AllerdingsWichtiger funktioniertHinweis daszum Export 📄

Mermaid (und auch Formeln) funktionieren bei mir nicht mitsauber derim Export-Funktion,Export d.h.(z. wennB. ein Besucher Buch X als PDF beispielsweise exportiert, dann sieht erPDF): statt Formelngerendertem undInhalt Diagrammen nurerscheinen Code-Blöcke.

Und das mit dem Exportieren funktioniert eh leider nicht bei mir, habe keine Ahnung warum und deshalb die Funktion einfach deaktiviert.

Ok, aber wieWie installiert man nunHacks dieals Hacks?Module?

–

Also denDen ersten Schritt haben wir getan,bereits indemgemacht: wir oben (inIn der YML-Datei)YML steht
APP_THEME=custom
definiertDadurch haben, was dafür sorgt, dass fortanwerden Module geladenaus werdenfolgendem können,Pfad diegeladen: sich

hier befinden: /opt/bookstack/bookstack/www/themes/custom/modules

Nun

muss manDann per SSH das eingeben:SSH:

In den Container wechseln:

• docker exec -it bookstack /bin/bash

Damit kann man dann Befehle „von innen“ heraus ausführen; Dann:Ins Web-Verzeichnis:

cd /app/www/; Und dort dannDort das Kommando ausführen, das hierim angezeigtjeweiligen wirdHack steht (am Beispiel Mermaid):

Auf der Hack-Seite im Abschnitt „Install as Module“
https://www.bookstackapp.com/hacks/mermaid-viewer/ Dort dann im Abschnitt: „Install as Module“…

Shift+Enter – Zeilenumbruch:Zeilenumbruch (CommonMark)

Da

sichDurch die EntwicklerEntscheidung auffür den CommonMark-Standard festgelegt haben, bedeutet es, dass u.a. standardmäßigwird ein einfacher Zeilenumbruch standardmäßig nicht gerendertgerendert. wird:Stattdessen Manbraucht mussman „zwei Spaces am Zeilenende schreiben+ und dann Enter, damit ein einfacher Linebreak stattfindetEnter“ – das hat mich wahnsinnig gemacht, weil alleviele Markdown-Editoren,Editoren dieShift+Enter ichgewohnt kennesind. funktionieren da anders (einfach Shift+Enter). Das wollte ich unbedingt ändern und habe dafür ein paar Stunden Zeit investiert. Jedenfalls sieht derMein Fix folgendermaßenbesteht aus:aus zwei Teilen:

1. HierIn (den BookStack-Einstellungen unter
   https://example.com/settings/customization)
   bei „Custom HTML Head Content“ diesenfolgenden Code eintragen:

    <script>
      window.addEventListener('editor-markdown::setup', event => {
        event.detail.markdownIt.set({breaks: true});
      });
    </script>
   

2. Dann hier eineEine functions.php anlegen:
   anlegen unter:
3. /opt/bookstack/bookstack/www/themes/custom/
   

Mit dem folgendenfolgendem Inhalt:

<?php

use BookStack\Theming\ThemeEvents;
use BookStack\Facades\Theme;

Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function ($environment) {
  $environment->mergeConfig([
    'renderer' => [
      'soft_break' => "<br>",
    ]
  ]);

  return $environment;
});

Weitere QoL-Fixes (einzustellenunter „Customization“) 🛠️

Einstellen hier:

https://deineurl.com/settings/customization)

Einfach jeweils unter „Custom HTML Head Content“ eintragen:

1. BlockquotesBlockquotes: habenkein keinen dickendicker Rand unten / saubere Abstände
2. Ursache: CSS (liegtu. am CSS, weil u.a. alle <p>-Elemente mit margin-bottom)

haben) - dieser Fix macht(gleicher obenAbstand und oben/unten den+ gleichenkeine Abstand:Scrollbalken):

 <style>
   /* 1) Letztes & erstes direktes Kindelement im Blockquote: Margin */
   .content-wrap blockquote > :last-child {
     margin-bottom: .3em;
   }

   .content-wrap blockquote > :first-child {
     margin-top: .3em;
   }

   /* 2) Blockquote: keine Scrollbalken */
   .content-wrap blockquote {
     overflow: visible;     /* Standard „ohne Scrollen“ */
     overflow-x: visible;
     overflow-y: visible;
   }
 </style>

Codeblöcke habenCodeblöcke: Soft-Wraps (alsokein manhorizontales mussScrollen nicht horizontal scrollen, um die ganze Zeile zu sehen):nötig)

 <script>
 window.addEventListener('library-cm6::pre-init', event => {
     const detail = event.detail;
     const config = detail.editorViewConfig;
     const EditorView = detail.libEditorView;

     if (detail.usage === 'content-code-block') {
         config.extensions.push(EditorView.lineWrapping);
     }
 });
 </script>

Dark Mode: Text im Dark-Mode heller machen (Überschriften werden grau 70%, normaler Text hell-grau 90%):

 <style>
 html.dark-mode .page-content h1, html.dark-mode .page-content h2, html.dark-mode .page-content h3, html.dark-mode .page-content h4, html.dark-mode .page-content h5, html.dark-mode .page-content h6 {
     color: hsl(0 0% 70%);
   }
   html.dark-mode body {
     color: hsl(0 0% 90%);
   }
 </style>

TextTextgröße: größer machen (Hauptinhalt wird auf 110% hochskaliert, aber, Überschriften auf 90% runter, weil ich sie als zu groß empfand):

 <style>
 .page-content {
     zoom:1.1;
   }

   .page-content h1, .page-content h2, .page-content h3, .page-content h4, .page-content h5, .page-content h6 {
     zoom:.9;
   }
 </style>

---

Wenn du willst, kann ich dir als nächsten Schritt noch eine „Checkliste vor dem Start“ (DNS, Ports 80/443, Firewall, APP_KEY-Generierung etc.) ergänzen – inhaltlich gleich, nur als schnell abhakbare Sektion.