Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen gezeigt.

--- thoschwiki:docker:apps:dokuwiki [30.08.2020 17:59]
thosch [Update des Images] ergänzt
+++ 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) ======
-**//DokuWiki//** ist eine standardkonforme, einfach zu verwendende und zugleich äußerst vielseitige Open Source [[wpde>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. ([[doku>de:dokowiki|Eigenbeschreibung des Projektes]])
+{{page>thoschwiki:bricks:dokuwiki#beschreibung&noheader}}
-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 ^^
@@ Zeile 29: / Zeile 25: @@
   -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 ====
@@ Zeile 40: / Zeile 38: @@
 | -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]]. |
-| -e APP_URL | Optional: Hier kann der Pfad vorgegeben werden, unter dem das Wiki auf dem Server zu erreichen ist (z.B. ''http://example.com/wiki'' statt ''http://example.com''). |
 | -p | Port-Zuweisungen für den Zugriff per ''http'' (Default 80:80) bzw. ''https'' (Default 443:443) |
 | -v * | Volumes, siehe [[#Volumes:|Unterabschnitt Volumes]] |
@@ Zeile 55: / Zeile 52: @@
 | /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  =====
@@ Zeile 65: / Zeile 61: @@
 services:
   dokuwiki:
-    image: linuxserver/dokuwiki
+    image: linuxserver/version-XXXX-XX-XX
     container_name: dokuwiki
     environment:
@@ Zeile 78: / Zeile 74: @@
     restart: unless-stopped
 </file>
+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 =====
@@ Zeile 88: / Zeile 88: @@
   dokuwiki:
-    image: linuxserver/dokuwiki
+    image: linuxserver/version-XXXX-XX-XX
     container_name: dokuwiki
     environment:
@@ Zeile 103: / Zeile 103: @@
 </code>
-==== Update des Images ====
+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 ====
-Beim Update des Images ist  Vorsicht geboten. Sofern sich die //DokuWiki//-Version im Image ändert, kann dies zu einem nicht mehr lauffähigen System führen.Die notwendige Migration der persistierten Daten, die sonst anlässlich des Upgrades von //DokuWiki// durchgeführt wird, ist in diesem Fall nicht erfolgt, und die Daten passen daher u.U. nicht zur neuen //DokuWiki//-Version.
-Die folgenden Vorgehensweise ist empfehlenswert:
+Sofern der Verdacht besteht, dass die neue //DokuWiki//-version nicht mit den Bestandsdaten kompatibel sein könnte, dann kann wie folgt vorgegangen werden:
-  -   Version des Images in der Produktionsumgebung durch Vorgabe des entsprechenden Tags pinnen.
+  -   Die neuen Version des Images zunächst in eine //getrennte Testinstanz einspielen// und mit einer Kopie der produktiven Daten testen.
-  -   Bei Verfügbarkeit einer neuen Version des Images diese zunächst in einer getrennten Testinstanz mit den 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).
-  -   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 2-4 das Update der Produktionsumgebung vornehmen und dabei die Version des Images auf die neue Version pinnen.
+  -   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