Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen gezeigt.

--- thoschwiki:docker:apps:dokuwiki [01.08.2020 15:13]
thosch Stub angelegt
+++ thoschwiki:docker:apps:dokuwiki [08.03.2022 10:03] (aktuell)
thosch [Integration in Træfik] Version-Pinning angepasst.
@@ Zeile 1: / Zeile 1: @@
-====== DokuWiki ======
+====== DokuWiki (Docker) ======
+{{page>thoschwiki:bricks:dokuwiki#beschreibung&noheader}}
+^ Image ^^
-^ linuxserver/dokuwiki ^^
 ^ Docker Hub | [[dockerhub>linuxserver/dokuwiki]] |
-^ GitHub | [[github>repo]] |
+^ GitHub | [[github>linuxserver/docker-dokuwiki]] |
-^ Projekt | |
+^ Architektur | x86-64, armhf, arm64 |
+^ **Software** ^^
+^ Projekt | [[doku>de:dokowiki|DokuWiki]] |
+^ GitHub | [[github>splitbrain/dokuwiki]] |
 ===== docker run =====
@@ Zeile 16: / Zeile 18: @@
 docker run -d \
   --name=dokuwiki \
-  -e PUID=1000 \
+  -e PUID=2000 \
-  -e PGID=1000 \
+  -e PGID=2000 \
   -e TZ=Europe/London \
-  -e APP_URL=/dokuwiki `#optional` \
   -p 80:80 \
-  -p 443:443 `#optional` \
+  -p 443:443 \
   -v /path/to/appdata/config:/config \
   --restart unless-stopped \
-  linuxserver/dokuwiki
+  linuxserver/dokuwiki:20XX-XX-XXX-lsXX
 </code>
+Im Hinblick auf [[thoschwiki:docker:apps:dokuwiki#update_des_images|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 [[wpde>Zeitzonen-Datenbank|Format Gebiet/Ort]]. |
+| -p | Port-Zuweisungen für den Zugriff per ''http'' (Default 80:80) bzw. ''https'' (Default 443:443) |
+| -v * | Volumes, siehe [[#Volumes:|Unterabschnitt Volumes]] |
+==== Volumes ====
+In der Konfiguration werden Volumes in der Regel im folgenden Format angegeben:
+<code><Pfad auf dem Host>:<Pfad im Container>[:<Optionen>]</code>
+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 [[wpde>Nginx|nginx]] einschließlich [[wpde>PHP]] sowie die Inhalte des //DokuWikis//. |
+Sofern sitespezifische Interwiki-Link-Icons benutzen werden sollen, ist eine [[thoschwiki:docker:apps:dokuwiki#persistieren_von_sitespezifischen_interwiki-link-icons|Änderung bei den Volumes]] vorzunehmen.
 ===== docker-compose  =====
 Der Container wird wie folgt in der ''docker-compose.yml'' konfiguriert:
-<code>  </code>
+<file - docker-compose-yml>
+version: "2.1"
+services:
+  dokuwiki:
+    image: linuxserver/version-XXXX-XX-XX
+    container_name: dokuwiki
+    environment:
+      - PUID=2000
+      - PGID=2000
+      - TZ=Europe/Berlin
+    volumes:
+      - /path/to/config:/config
+    ports:
+      - 80:80
+      - 443:443
+    restart: unless-stopped
+</file>
-==== Integration in Træfik ====
+Im Hinblick auf [[thoschwiki:docker:apps:dokuwiki#update_des_images|mögliche Probleme bei einem unbeabsichtigten Update des Images]] sollte die Version des Images durch das Anfügen des Versions-Tags (Format ''version-XXXX-XX-XX'') gepinnt werden.
+Sofern sitespezifische Interwiki-Link-Icons benutzen werden sollen, ist eine [[thoschwiki:docker:apps:dokuwiki#persistieren_von_sitespezifischen_interwiki-link-icons|Ä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:
-<code>  </code>
+<code>
+...
+  dokuwiki:
+    image: linuxserver/version-XXXX-XX-XX
+    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"
+</code>
+Im Hinblick auf [[thoschwiki:docker:apps:dokuwiki#update_des_images|mögliche Probleme bei einem unbeabsichtigten Update des Images]] sollte die Version des Images durch das Anfügen des Versions-Tags (Format ''version-XXXX-XX-XX'') gepinnt werden.
+Sofern sitespezifische Interwiki-Link-Icons benutzen werden sollen, ist eine [[thoschwiki:docker:apps:dokuwiki#persistieren_von_sitespezifischen_interwiki-link-icons|Ä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%%'')
+===== Persistieren von sitespezifischen Interwiki-Link-Icons =====
+Das DokuWiki unterstütz das Konzept der [[doku>de:interwiki|Interwiki-Links]]. Hierbei handelt es sich um vordefinierte, verkürzte Markups (Shortcuts) zum Verlinken auf andere Wikis. Es ist möglich eigene [[thoschwiki:dokuwiki:interwikilinkshortcuts|Shortcuts für Interwiki-Links]] zu definieren. Vor den Interwiki-Links wird eine kleine Grafik von 16x16 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 [[dockerhub>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
+  - einen zusätzlichen, minimalen DokuWiki-Container generiert, bei dem das Volume für die Icons das Verzeichnis ''lib/images'' nicht überdeckt
+  - per ''docker exec'' innerhalb des Containers die System-Icons in das Volume kopiert (sowie die Rechte berichtigt) sowie
+  - den Hilfs-Container beendet und zerstört
+<code bash>
+#!/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."
+</code>
+==== Ä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 [[wpde>Nginx|nginx]] einschließlich [[wpde>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:
+<code>
+    volumes:
+      - /path/to/DokuWiki/config:/config
+      - /path/to//DokuWiki/images:/app/dokuwiki/lib/images
+</code>
+===== Update des Images =====
+Das Image wird -- wie bei [[dockerhub>linuxserver]] üblich -- häufig aktualisert. Hierbei scheint die Aktualisierung der Basiskomponenten ([[wpde>Linux|Linux-Komponenten]], Webserver [[wpde>Nginx|nginx]] einschließlich [[wpde>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.
+<note tip>
+Die beschriebenen Problem mit der //Dokuwiki//-version kann man umgehen, indem man für das Image ein Labl mit der jeweiligen //Dokuwiki//-Version nutzt. Derzeit (März 2022 ist dies das Label ''version-2020-07-29''.
+Bei Verwendung des Labels werden nur Images geladen, die die vorgebene //Dokuwiki//-version enthalten. Ändert sich diese sollten keine neuen Images mehr geladen werden.
+Ändert sich die //Dokuwiki//-Version wären die in der Folge beschriebenen Schritte einzuhalten und das Label entsprechend anzupassen.
+</note>
+==== 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 [[dockerhub>linuxserver/dokuwiki/tags|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 [[doku>changes|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:
+  -   Die neuen Version des Images zunächst in eine //getrennte Testinstanz einspielen// und mit einer Kopie der produktiven Daten testen.
+  -   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 [[doku>plugin:upgrade|upgrade Plugin]]) im laufenden Container updaten (ggf. ist es notwendig vorab die produktiven Daten neu vom Produktionssystem abzuziehen und erneut einzuspielen).
+  -   Danach erneut neue Image-Version in die Testversion einspielen und testen.
+  -   Entsprechend den Ergebnissen aus den Punkten 1-3 das Update der Produktionsumgebung vornehmen. Hierbei ist die Version wieder zu pinnen.

ThoSch:Wiki

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Unterschiede

Seiten-Werkzeuge