Zur Installation von Bookstack wird ein von Bookstack angebotenes Script genutzt, dass Bookstack, Apache, MySQL und PHP automatisch installiert. Die jeweils aktuellen Versionen sind dazu hier beschrieben: Installation · BookStack (bookstackapp.com)

Voraussetzungen

Vorraussetzung ist in diesem Fall ein frisch installiertes und aktualisiertes Ubuntu 22.04 Server (ohne UI) mit Internetverbindung.

Installation

Folgende drei Befehle führen die Installation aus. Dabei wird zuerst das Script heruntergeladen, anschließend die heruntergeladende Datei als ausführbar geflagged und anschließend die Datei ausgeführt:

wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-22.04.sh
chmod a+x installation-ubuntu-22.04.sh
sudo ./installation-ubuntu-22.04.sh

Das Skript fragt nun nach der Domäne oder IP, über die Bookstack erreichbar sein soll. z.B. docs.example.com. Nun läuft das Skript einige Installationsschritte durch. Abschließend erfolgt eine Ausgabe mit den Informationen, wie BookStack nun erreichbar ist und wo weitere Infos zur Installation zu finden sind. z.B.

----------------------------------------------------------------
Setup finished, your BookStack instance should now be installed!
- Default login email: admin@admin.com
- Default login password: password
- Access URL: http://192.168.0.10 or http://docs.example.com/
- BookStack install path: /var/www/bookstack
- Install script log: /home/user/bookstack_install_1702768207.log
---------------------------------------------------------------

E-Mailserver konfigurieren

Im automatischen Installationsskript ist keine Konfiguration des E-Mail-Servers zum Versenden von Mails inkludiert. Führe auf dem Server folgenden Befehl aus um die Konfiugrationsdatei von Bookstack zu editieren:

sudo nano /var/www/bookstack/.env

Ersetze folgende Werte mit den Werten für den eigenen Mailserver.

MAIL_FROM_NAME="Bookstack"
MAIL_FROM=anything@yourdomain.tld
MAIL_HOST=your.mailserver.com
MAIL_PORT=587
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

Folgendes muss angepasst werden:

MAIL_FROM_NAME: Der Name, der als Absender der E-Mails angezeigt wird
MAIL_FROM: Die E-Mailadresse, die als Absender verwendet wird
MAIL_HOST: Die MX-Adresse des zu verwendenden Mailservers
MAIL_PORT: Der Port, welcher zu nutzen ist. Standardports: 25 = SMTP (unverschlüsselt), 587 = StartTLS, 465 = TLS/SSL
MAIL_USERNAME: Benutzername, der zur Authentifizierung verwendet wird
MAIL_PASSWORD: Das dazugehörige Passwort
MAIL_ENCRYPTION: null = keine Verschlüsselung (unverschlüsseltes SMTP), tls = TLS/SSL verschlüsselt, starttls = StartTLS verschlüsselt

Abschließend den Apache Dienst einmal neu starten um die Änderungen anzuwenden:

sudo systemctl restart apache2

Mailserver mit Microsoft 365 einrichten

Um einen Mailserver mit Microsoft 365 (ehemals Office 365) einzurichten, kann folgende Methode (Option 2) benutzt werden. Hierbei ist nur E-Mailversand innerhalb der eigenen Domäne(n) möglich. Es wird StartTLS über Port 25 oder unverschlüsseltes SMTP über Port 25 verwendet. Dafür wird keine extra Lizenz benötigt: Einrichten eines Multifunktionsgeräts oder einer Anwendung zum Senden von E-Mails mithilfe von Microsoft 365 oder Office 365 | Microsoft Learn

Zusammengefasst müssen die E-Mail-Einstellung in der settings.yaml wie folgt gesetzt werden (Ersetze die Platzhalter entsprechend mit den Werten der zu nutzenden M365 Instanz):

MAIL_FROM_NAME="Bookstack"
MAIL_FROM=anything@yourdomain.tld
MAIL_HOST=your.mxendpoint.example.outlook.com
MAIL_PORT=25
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=tls

Um zu verhindern, dass die E-Mails als Spam deklariert werden, kann ein SPF-Eintrag in den DNS-Einstellungen der Domäne gesetzt werden, wenn eine statische IP für den Internetanschluss genutzt wird. Dazu folgenden TXT-DNS-Eintrag der SPF-Settings mit folgendem Wert ergänzen: v=spf1 ip4:<Static IP Address> include:spf.protection.outlook.com ~all Da es vom DNS Anbieter abhängig ist wie genau dies konfiguriert wird, kann an dieser Stelle nicht im Detail darauf eingegangen werden, wie dies geschieht. Ggf. bitte den DNS-Anbieter kontaktieren.

Auf Bookstack zugreifen

Erste Anmeldung

Für die erste Anmeldung die Daten aus der Ausgabe der Konsole nutzen um auf Bookstack zuzugreifen und sich mit dem Admin via Browser anzumelden.

Neuen Admin anlegen

Aus Sicherheitsgründen sollte nun zunächst ein neuer Admin angelegt werden. Dazu rechts oben auf Settings klicken und anschließend auf den Reiter Users. Nun auf die Schaltfläche Add new user klicken. Nun einen Namen für den neuen Admin definieren sowie dessen E-Mail-Adresse. Außerdem die Checkbox Admin aktivieren um diesen User auch wirklich zum Admin zu machen. Den Haken bei Send user invite email entfernen und in die beiden Passwort-Felder das neue Passwort es Users eingeben. Abschließend auf die Schaltfläche Save klicken. Nachdem der neue Admin erstellt wurde, wird der vorhandene Admin gelöscht. Dies hat den Sinn, dass der Standard-Adminuser nun nicht mehr existiert und für mögliche Angriffe nicht mehr zur Verfügung steht. Dazu den admin-user bearbeiten und auf die Schaltfläche Delete User klicken. Nun folgt ein Bestätigungs-Dialog. Hier den neuen Adminuser als “Nachfolger” des Admins auswählen und mit Confirm bestätigen. Da wir mit dem gelöschten User derzeit angemeldet sind, werden wir nun automatisch abgemeldet. Dafür können wir uns jetzt mit dem neuen Admin-User anmelden und fortfahren.

Zugriff auf Bilddateien erschweren

Um die URLs für Bilder, die ggf. an Inhalten angehängt sind, nicht so leicht zu erraten, kann man eine Option aktivieren, die zufällige Zeichenfolge vor den Dateinamen schreibt. Generell können alle Leute mit Zugriff auf die BookStack-URL die Bild-URLs aufrufen - egal welche Rechte sie besitzen. Diese Option lässt sich hier aktivieren:

BookStack anpassen

in den Settings unter Customization lassen sich einige visuellen Aspekte von BookStack anpassen. Diese sind im Einzelnen:

Application Name: Der Text, der links oben neben dem Icon angezeigt wird
Default Page Editor: Per Standard ist dies ein WYSIWYG (What You See Is What You Get) Editor eingestellt. Hier lassen sich Inhalte ähnlich wie in Word erstellen. Die Alternative, welche vor allem für technisch versierte Nutzer interessant ist, ist ein Markdown-Editor, welcher den Markdown-Syntax nutzt um Inhalte zu erstellen.
Application Logo: Das Icon, welches links oben und an einigen weiteren Stellen angezeigt wird
Application Icon: Das Icon, was im Browser z.B. bei der Anzeige von Tabs verwendet wird
Application Color Scheme: Hier lässt sich das Aussehen von Bookstack verändern. Wer hier Änderungen durchführen möchte, sollte sich Zeit nehmen um die Farben gut aufeinander abzustimmen.
Application Homepage: Welche Seite von Bookstack soll nach der Anmeldung angezeigt werden.
Footer Links: Am Ende der Seite von Bookstack lassen sich weitere Links platzieren. z.B. zu Datenschutzinformationen, Kontaktformularen, Impressum oder auch interne Unternehmenslinks.
Custom HTML Head Content: Hier können eigene Elemente in den <head>-HTML-Tag eingefügt werden. z.B. um Suchmaschinen zu steuern, CSS zu überschreiben oder Tracking zu implementieren.

Bookstack via HTTPS nutzen

Zertifikat erzeugen

Es wird ein valides öffentliches Zertifikat benötigt (.pem), dem alle Clients, die zu Bookstack verbinden sollen, vertrauen. Ebenso der dazugehördende private Schlüssel (.key). Wenn von einer Windows Zertifikatsstelle eine .pfx-Datei erzeugt wurde, welche sowohl das öffentliche Zertifikat als auch den privaten Schlüssel enthält, so können wie folgt die .pem- und .key-Dateien daraus erzeugt werden:

Das öffentliche Zertifikat extrahieren (.pem):

openssl pkcs12 -in cert.pfx -out cert.pem -nokeys -clcerts

Den privaten Schlüssel extrahieren (.key):

openssl pkcs12 -in cert.pfx -out cert.key -nocerts -nodes

Wenn die .pem nicht die vollständige Zertifizierungskette enthält, z.B. weil diese aus der .pfx-Datei extrahiert wurde, dann muss das öffentlichen Stammzertifizierungsstellenzertifikat der .pem-Datei noch angefügt werden (z.B. mit nano). Die .pem-Datei sieht dann am Ende wie folgt aus (ggf. sind am Begin noch einige Attribute enthalten):

-----BEGIN CERTIFICATE-----
MIIF9zCCBN+gAwIBAgITGwAAAAjgOR0bKF2AlwAAAAAACDANBgkqhkiG9w0BAQsF
...
inNyFgDzqdN8Y182+Da3iyQ4fz7pjySjyJlwk9GCJAwZLQtaudyKGInBKg==
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIDZzCCAk+gAwIBAgIQbwVSTbcyOrhIUgWXRTgKvDANBgkqhkiG9w0BAQsFADBF
...
38qV3rsb6mxhdgQ=
-----END CERTIFICATE-----

Das erste Zertifikat ist das öffentliche Zertifikat des Bookstack-Servers. Das zweite Zertifikat ist das Zertifikat der Stammzertifizierungsstelle.

Kopiere diese beiden Dateien nach /etc/ssl/ mit den Befehlen sudo cp cert.pem /etc/ssl und sudo cp cert.key /etc/ssl.

Apache config anpassen Nun die Apache-Konfigurationsdatei sichern:

sudo mv /etc/apache2/sites-available/bookstack.conf /etc/apache2/sites-available/bookstack.conf.old

und eine Neue erstellen:

sudo nano /etc/apache2/sites-available/bookstack.conf

Hier nun folgenden Inhalt einfügen und ServerName und SSLCertificate ggf. anpassen:

<VirtualHost *:80>
    ServerName YOUR-DOMAIN-HERE
    RewriteEngine On
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>

<VirtualHost *:443>
	ServerName YOUR-DOMAIN-HERE
	ServerAdmin webmaster@localhost
	DocumentRoot /var/www/bookstack/public/

    SSLEngine on
    SSLCertificateFile      /etc/ssl/cert.pem
    SSLCertificateKeyFile   /etc/ssl/cert.key

    <Directory /var/www/bookstack/public/>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
        <IfModule mod_rewrite.c>
            <IfModule mod_negotiation.c>
                Options -MultiViews -Indexes
            </IfModule>
            RewriteEngine On
            # Handle Authorization Header
            RewriteCond %{HTTP:Authorization} .
            RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
            # Redirect Trailing Slashes If Not A Folder...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_URI} (.+)/$
            RewriteRule ^ %1 [L,R=301]
            # Handle Front Controller...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        </IfModule>
    </Directory>

	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Des Weiteren benötigt noch der Apache des SSL Modul:

sudo a2enmod ssl

Nun die config testen:

sudo apachectl configtest

Das Ergebnis sollte Syntax OK beinhalten.

Jetzt die Bookstack-Config editieren:

sudo nano /var/www/bookstack/.env

und dort die APP_URL-Variable auf https://.... ändern.

Zuletzt den Apache neu starten:

sudo systemctl restart apache2

Fertig.

BookStack Wiki Installieren