DokuWiki (Docker) [ThoSch:Wiki]

Benutzer-Werkzeuge

Webseiten-Werkzeuge


thoschwiki:docker:apps:dokuwiki

DokuWiki (Docker)

DokuWiki ist eine standardkonforme, einfach zu verwendende und zugleich äußerst vielseitige Open Source Wiki-Software. Die Anwendung nutzt einfache Textdateien zur Speicherung der Inhalte und benötigt insofern keine Datenbank. Der integrierte Konfigurations-Manager erlaubt es, Einstellungen direkt über eine Anwenderfreundliche Web-Oberfläche vorzunehmen. (Eigenbeschreibung des Projektes)

Durch die Ablage der Konfiguration und der Inhalte im Dateisystem werden das Backup, manuelle Eingriffe sowie auch eine Migration bzw. eine Replikation auf andere Instanzen deutlich erleichtert.

Der Verzicht auf eine Datenbank reduziert auch die Anforderungen an die verfügbaren Systenressourcen.

Image
Docker Hub linuxserver/dokuwiki
GitHub linuxserver/docker-dokuwiki
Architektur x86-64, armhf, arm64
Software
Projekt DokuWiki
GitHub splitbrain/dokuwiki

docker run

Der Container wird wie folgt mit docker run eingerichtet und gestartet:

docker run -d \ 
  --name=dokuwiki \
  -e PUID=2000 \
  -e PGID=2000 \
  -e TZ=Europe/London \
  -p 80:80 \
  -p 443:443 \
  -v /path/to/appdata/config:/config \
  --restart unless-stopped \
  linuxserver/dokuwiki:20XX-XX-XXX-lsXX

Im Hinblick auf mögliche Probleme bei einem unbeabsichtigten Update des Images sollte die Version des Images durch das Anfügen des Versions-Tags (Format 20XX-XX-XXX-lsXX) gepinnt werden.

Parameter

Dies sind die wichtigsten Parameter. Sofern sie mit einem „*“ markiert sind, sollte eine Anpassung erfolgen:

Parameter Funktion
-e PUID= * Vorgabe des Users , mit dem die Daten auf dem Docker-Host in die gemounteten Verzeichnisse geschrieben werden.
-e PGID= * Vorgabe des Gruppe , mit der die Daten auf dem Docker-Host in die gemounteten Verzeichnisse geschrieben werden.
-e TZ= * Vorgabe der lokalen Zeitzone im Format Gebiet/Ort.
-p Port-Zuweisungen für den Zugriff per http (Default 80:80) bzw. https (Default 443:443)
-v * Volumes, siehe Unterabschnitt Volumes

Volumes

In der Konfiguration werden Volumes in der Regel im folgenden Format angegeben:

<Pfad auf dem Host>:<Pfad im Container>[:<Optionen>]

Die Volumes haben die folgenden Funktionen (maßgeblich ist der Pfad im Container):

Pfad im Container Funktion
/config In bzw. unterhalb dieses Ordners befinden sich die Konfigurationsdateien des DokuWiki, des Webservers nginx einschließlich PHP sowie die Inhalte des DokuWikis.

Sofern sitespezifische Interwiki-Link-Icons benutzen werden sollen, ist eine Änderung bei den Volumes vorzunehmen.

docker-compose

Der Container wird wie folgt in der docker-compose.yml konfiguriert:

docker-compose-yml
version: "2.1"
services:
  dokuwiki:
    image: linuxserver/dokuwiki:20XX-XX-XXX-lsXX
    container_name: dokuwiki
    environment:
      - PUID=2000
      - PGID=2000
      - TZ=Europe/Berlin
    volumes:
      - /path/to/config:/config
    ports:
      - 80:80
      - 443:443
    restart: unless-stopped

Im Hinblick auf mögliche Probleme bei einem unbeabsichtigten Update des Images sollte die Version des Images durch das Anfügen des Versions-Tags (Format 20XX-XX-XXX-lsXX) gepinnt werden.

Sofern sitespezifische Interwiki-Link-Icons benutzen werden sollen, ist eine Änderung bei den Volumes und somit an der docker-compose.yml vorzunehmen.

Integration in Træfik

Der Container kann mit den folgenden Eintragungen in der docker-compose.yml in Træfik integriert werden:

 
...

  dokuwiki:
    image: linuxserver/dokuwiki:20XX-XX-XXX-lsXX
    container_name: dokuwiki
    environment:
      - PUID=2000
      - PGID=2000
      - TZ=Europe/Berlin
    volumes:
      - /path/to/config:/config
    restart: unless-stopped
    labels:
     - traefik.http.routers.dokuwiki.rule=Host(`wiki.example.com`)
     - "traefik.http.routers.dokuwiki.tls.certResolver=default"
     - "traefik.http.routers.dokuwiki.tls=true"

Im Hinblick auf mögliche Probleme bei einem unbeabsichtigten Update des Images sollte die Version des Images durch das Anfügen des Versions-Tags (Format 20XX-XX-XXX-lsXX) gepinnt werden.

Sofern sitespezifische Interwiki-Link-Icons benutzen werden sollen, ist eine Änderung bei den Volumes und somit an der docker-compose.yml vorzunehmen.

Konfiguration der Anwendung

Für die Ersteinrichtung des DokuWikis ist in der Installation das Script /install.php aufzurufen (Aufruf von http[s]://$IP[:$PORT]/install.php bzw. http[s]://$DOMAIN[:$PORT]/install.php)

Das DokuWiki unterstütz das Konzept der Interwiki-Links. Hierbei handelt es sich um vordefinierte, verkürzte Markups (Shortcuts) zum Verlinken auf andere Wikis. Es ist möglich eigene Shortcuts für Interwiki-Links zu definieren. Vor den Interwiki-Links wird eine kleine Grafik von 16×16 Pixeln angezeigt. Es ist möglich für die eigenen Shortcuts eigene Icons zu hinterlegen.

Diese Grafikdateien sind im Verzeichnis lib/images/interwiki abgelegt. Beim Einsatz des DokuWiki in einem Docker-Container -– zumindest bei Verwendung des Images linuxserver/dokuwiki -– tritt das Problem auf, dass sich das Verzeichnis lib/images/interwiki außerhalb des vorgesehenen Volumes befindet und somit bei jedem Neuerstellen des Containers mit den Werten aus dem Image überschrieben wird.

Um dieses Problem zu lösen, habe ich ein zusätzliches Volume eingeführt, dass unter /app/dokuwiki/lib/images im Container gemountet wird. Durch die Verwendung dieses Mountpoints werden nicht nur die Icons für die Interwiki-Links, sondern alle Emojis und Interwiki-Link-Icons außerhalb des Containers gespeichert.

Vorbereitende Arbeiten

Das Mounten des Volumes nach /app/dokuwiki/lib/images führt dazu, dass das bestehende Verzeichnis /app/dokuwiki/lib/images im Image mit den systemseitigen Grafiken durch das gemountete Volume überdeckt wird. Ohne diese Dateien fehlen die entsprechenden Grafiken.

Das Volume ist daher mit dem systemseitigen Grafiken initial zu „befüllen“. Hierfür habe ich ein Helfer-Script geschrieben, das

  1. einen zusätzlichen, minimalen DokuWiki-Container generiert, bei dem das Volume für die Icons das Verzeichnis lib/images nicht überdeckt
  2. per docker exec innerhalb des Containers die System-Icons in das Volume kopiert (sowie die Rechte berichtigt) sowie
  3. den Hilfs-Container beendet und zerstört
#!/bin/sh
#
# Helper script to copy the icons from an complete container into
# the volume which will contain and persist the icons
 
echo "Start Container..."
 
# Minimal container w/o port etc. and mounted 'images' volume
docker run \
  --name=dokuwikihelper \
  -d \
  --rm \
  -e PUID=2000 \
  -e PGID=2000 \
  -e TZ=Europe/Berlin \
  -v /path/to/DockerData/DokuWiki/images:/images \
  linuxserver/dokuwiki
 
 
echo
echo "Kopiere Dateien..."
# Copy icons to mounted volume
# ('cp -a /app/dokuwiki/lib/images/* /images' did not work...)
docker exec -it dokuwikihelper cp -a /app/dokuwiki/lib/images /
# Change owner to 'abc' which is used to run DokuWiki in the container
# to prevent that 'root' is the owner
docker exec -it dokuwikihelper chown abc:abc -R /images
 
echo
echo "ls -axl /path/to/DockerData/DokuWiki/images"
ls -axl /path/to/DockerData/DokuWiki/images
 
echo
echo "Stoppe Container..."
docker stop dokuwikihelper
 
echo "Die eigenen Icons sind noch nach /path/to/DockerData/DokuWiki/images"
echo "bzw. /path/to/DockerData/DokuWiki/images/interwiki zu kopieren und"
echo "ggf. die Dateirechte anzupassen."

Änderungen der Volume-Definition

Es ergeben sich damit die folgenden Volumes:

Pfad im Container Funktion
/config In bzw. unterhalb dieses Ordners befinden sich die Konfigurationsdateien des DokuWiki, des Webservers nginx einschließlich PHP sowie die Inhalte des DokuWikis.
/app/dokuwiki/lib/images Verzeichnis mit den Wiki-seitigen Grafikdateien

Die Definition der Volumes in der docker-compose.yml ändert sich wie folgt:

    volumes:
      - /path/to/DokuWiki/config:/config
      - /path/to//DokuWiki/images:/app/dokuwiki/lib/images

Update des Images

Das Image wird – wie bei linuxserver üblich – häufig aktualisert. Hierbei scheint die Aktualisierung der Basiskomponenten (Linux-Komponenten, Webserver nginx einschließlich PHP) im Vordergrund zu stehen. Änderungen an der Struktur des Images scheinen eher selten zu sein. Beim Bau des Images wird die aktuelle Stable-Version von DokuWiki im Image installiert. Im Changelog erscheinen jedoch nur die vorgenommenen Änderungen an der Struktur des Images.

Sofern sich die DokuWiki-Version im Docker-Image ändert, kann es nach dem Update des Images zu einem nicht mehr lauffähigen System kommen. Die neue Version von DokuWiki kann u.U. Änderungen der Datenstrukturen vorsehen, die eine Anpassung (Migration) der Bestandsdaten aus der Vorversion erforderlich machen. Bei einer „normalen“ Installation ohne den Einsatz von Docker erfolgt diese Migration anlässlich des Upgrades von DokuWiki. Erfolgt das Update von DokuWiki jedoch durch den Austausch der DokuWiki-Software im Rahmen des Updates des Images, dann laufen die notwendigen Migrationsroutinen nicht. In der Folgen passen die Daten dann nicht zur neuen DokuWiki-Version.

Identifikation kritischer Updates

Da im Changelog des Images nicht auf eine ggf. neue DokuWiki-Version hingewiesen wird, ist es notwendig, dass bei jeder neuen Imageversion vor dem Einspielen geprüft wird, ob das Image eine neue DokuWiki-Version enthält.

Aufgrund der Struktur der Versionsbezeichnung ist dies leicht möglich. Die Versionsbezeichnung baut sich wie folgt auf:

JJJJ-MM-TT[x]-lsXX

Die ersten acht (bis neun) durch zwei Bindestriche strukturierten Zeichen geben das Datum des DokuWiki-Releases ggf. mit einem Buchstaben für die Bezeichnung des Hotfixes an. Der mit „ls“ beginnende Teil ist die interne Versionsnummer von Linuxservers.io.

Um die Versionsbezeichnung des aktuellen Images zu ermitteln, muss man die Tags-Registerkarte des Repositories auswerten. Die Bezeichnung der aktuellen Version sollte sich regelmäßig im zweiten Eintrag befinden.

Solange sich der erste, DokuWiki-bezogene Teil der Versionsbezeichnung nicht ändert, besteht kein Risiko einer zu den Bestandsdaten inkompatiblen Imageversion.

Beispiel
Bezeichnung Anmerkung
2018-04-22c-ls40 Image ls40 mit DokuWiki-Release 2018-04-22c “Greebo” - Erstinstallation
2018-04-22c-ls41 Image ls41 mit DokuWiki-Release 2018-04-22c “Greebo”
Es sind keine Probleme beim Update zu erwarten.
2020-07-29-ls42 Image ls42 mit dem neuen DokuWiki-Release 2020-07-29 “Hogfather”
:!: Hier kam es aufgrund des neuen DokuWiki-Releases zu massiven Probleme mit den Bestandsdaten.
2020-07-29-ls43 Image ls43 mit dem DokuWiki-Release 2020-07-29 “Hogfather”
Sofern bereits auf Version ls43 geupdatet wurde, sind keine Probleme beim Update zu erwarten.

Sofern sich die Bezeichnung des DokuWiki-Releases ändert, sollte anhand des Changelogs geprüft werden, welche Änderungen vorliegen. Zumindest wenn sich das Majorsrelease ändert (Änderung des Datums „2018-04-22“ → „2020-07-29“ und der Namens „Greebo“ → „Hogfather“) ist Vorsicht geboten.

Einspielen kritischer Updates

Sofern der Verdacht besteht, dass die neue DokuWiki-version nicht mit den Bestandsdaten kompatibel sein könnte, dann kann wie folgt vorgegangen werden:

  1. Die neuen Version des Images zunächst in eine getrennte Testinstanz einspielen und mit einer Kopie der produktiven Daten testen.
  2. Sofern das Testsystem mit der neuen Images-Version nicht mehr lauffähig ist: Roll-Back der Testinstanz auf die bisherige Version vornehmen und das DokuWiki mit „Bordmitteln“ (z.B. mit dem upgrade Plugin) im laufenden Container updaten (ggf. ist es notwendig vorab die produktiven Daten neu vom Produktionssystem abzuziehen und erneut einzuspielen).
  3. Danach erneut neue Image-Version in die Testversion einspielen und testen.
  4. Entsprechend den Ergebnissen aus den Punkten 1-3 das Update der Produktionsumgebung vornehmen. Hierbei ist die Version wieder zu pinnen.
thoschwiki/docker/apps/dokuwiki.txt · Zuletzt geändert: 10.10.2020 20:30 von thosch