Eine Komponente installieren

Von einer frischen DokuWiki-Instanz zu einer Komponente, von der Sie belegen können, dass sie läuft. Rechnen Sie mit fünf Minuten je Komponente, zuzüglich der Erstkonfiguration derjenigen, die eine brauchen.

Das Verfahren ist für alle Komponenten dieses Hauses dasselbe. Was sich je Komponente unterscheidet — welche anderen sie voraussetzt, was Sie danach einstellen müssen, woran Sie den Erfolg erkennen —, steht in der Komponentenmatrix und, für Ihre konkrete Auswahl, im Paket-Baukasten.

Voraussetzungen

DokuWiki, geprüft auf der Fassung 2026-07-14b „Mort„. Ältere Fassungen sind nicht ausgeschlossen, aber auch nicht geprüft; die Angaben zum Erweiterungsmanager auf dieser Seite gelten für diese Fassung.
PHP 8.2 oder neuer. Einzelne Komponenten kommen mit weniger aus, die Mehrheit nicht; die Fassung ist Voraussetzung der Suite und nicht je Komponente verhandelbar.
Der PDO-Treiber für SQLite, sobald eine Komponente Daten speichert. Ohne ihn lädt die Komponente, findet aber keine Datenbank und schaltet ihre speichernden Funktionen ab. Prüfen: php -r "var_dump(in_array('sqlite', PDO::getAvailableDrivers()));" muss bool(true) ausgeben.
Schreibrechte des Webserver-Kontos auf lib/plugins/ (bzw. lib/tpl/), conf/ und data/. Ohne sie ist nur die Installation von Hand möglich.
Ein Administratorkonto im Wiki, also ein Konto, das ?do=admin öffnen darf.
Zugang zum Paket-Baukasten dieses Wikis, oder zu den Repositories der Komponenten (siehe Schritt 1). Die Pakete dieses Hauses liegen nicht auf dokuwiki.org; die Suchfunktion des Erweiterungsmanagers findet sie deshalb nicht.

Legen Sie eine Sicherung an, bevor Sie in ein Wiki mit Inhalt installieren. Eine Installation schreibt zwar nur in das Verzeichnis der Komponente, doch die erste Benutzung legt Datenbanken und Konfigurationsschlüssel an. Das Verfahren steht unter Die Sicherung.

Schritt 1: Das Paket zusammenstellen

Öffnen Sie den Paket-Baukasten, wählen Sie die Komponenten und die Funktionen, die Sie benutzen wollen, und laden Sie das Archiv herunter.

Damit ist Schritt 1 erledigt, und zwar vollständig: Der Baukasten löst die Abhängigkeiten transitiv auf. Sie müssen nicht wissen, dass wkdoadogit wkdostorage voraussetzt und wkdostorage seinerseits wkstorage. Sie müssen auch nicht raten, ob wkdoado für Ihren Fall nötig ist: Wenn Sie die Funktion Azure-DevOps-Repositories verwenden ankreuzen, ist es nötig, und dann steht es im Paket.

Vor dem Herunterladen zeigt der Baukasten, was er beschlossen hat:

was Sie ausgewählt haben,
was automatisch dazukommt und warum — zwingend erforderlich oder für eine von Ihnen gewählte Funktion,
was er empfiehlt und bewusst nicht einpackt,
welche Voraussetzungen die Zusammenstellung insgesamt an Ihren Server stellt,
welche Einschränkungen danach gelten,
in welcher Reihenfolge zu installieren ist.

Das Archiv enthält dieselben Angaben noch einmal als README.txt und manifest.json, dazu checksums.sha256 mit einer Prüfsumme je Datei.

Warum die Reihenfolge überhaupt eine Rolle spielt. Die Komponenten sind lose gekoppelt: Sie melden Dienste bei wkcore an und holen sich die Dienste anderer von dort. Eine falsche Reihenfolge zerstört daher nichts — die Dienste sind schlicht noch nicht da, und die abhängige Komponente arbeitet in ihrem eingeschränkten Modus weiter. Ärgerlich ist das trotzdem, weil das Ergebnis genau wie ein Fehler aussieht.

Die berechneten Stufen für alle Komponenten stehen in der Komponentenmatrix. Für Ihre Auswahl steht die Reihenfolge im Paket.

Kanal: Stabil oder Aktuell

Kanal	Woraus gebaut wird	Wann
Stabil	Die Fassung, die jede Komponente in ihrem Manifest festgeschrieben hat.	Die Vorgabe. Der Inhalt ist nachvollziehbar reproduzierbar; das Manifest im Archiv nennt je Komponente die verwendete Revision.
Aktuell	Der jeweils neueste Stand jeder Komponente.	Zum Erproben. Reproduzierbar nur über die im Manifest vermerkte Commit-Kennung.

Eine Komponente, für die noch keine Fassung festgeschrieben ist, wird auf dem Kanal Stabil abgelehnt und namentlich genannt — statt stillschweigend den aktuellen Stand einzupacken und ihn stabil zu nennen.

Wenn Sie den Baukasten nicht benutzen wollen

Jede Komponente ist ein eigenes Git-Repository, benannt wie ihre Kennung. Es gibt keine gemeinsame Fassung der Suite — jede Komponente trägt ihr eigenes Datum in plugin.info.txt.

Aus einem Klon. Klonen Sie das Repository und benutzen Sie den Arbeitsbaum als Paket. Die Abhängigkeiten ermitteln Sie dann selbst aus der Abhängigkeitstabelle — und zwar transitiv, also auch die Abhängigkeiten der Abhängigkeiten.

Über die REST-Schnittstelle des Servers. Der Server bietet je Repository einen ZIP-Abzug eines Zweiges an. Dieser Weg braucht ein persönliches Zugriffstoken mit Leserecht auf Code und ist für die Werkzeuge dieses Hauses gedacht, nicht für den Bezug einzelner Komponenten von Hand:

curl -f -u ":$PAT" -H "Accept: application/zip" -o wkcore.zip \
  "https://<devops-host>/<organisation>/<projekt>/_apis/git/repositories/wkcore/items?path=/&versionDescriptor.versionType=branch&versionDescriptor.version=main&\$format=zip&download=true&api-version=7.0"

Dieser Weg liefert eine Komponente, ohne Abhängigkeiten, ohne Prüfsummen und ohne die Angabe, welche Fassung Sie gerade bekommen haben. Für den gewöhnlichen Bezug ist der Baukasten der vorgesehene Weg; er braucht kein Token und geht über einen kontrollierten Endpunkt dieses Wikis.

Der ZIP-Abzug enthält die Dateien ohne umschließenden Ordner — plugin.info.txt liegt direkt in der Wurzel des Archivs. Das ist kein Problem: DokuWikis Erweiterungsmanager sucht plugin.info.txt bzw. template.info.txt an beliebiger Stelle im Archiv und leitet das Zielverzeichnis aus deren Feld base ab, nicht aus dem Namen des Archivs oder eines Ordners darin. Das Paket aus dem Baukasten ist anders gebaut: Es enthält bereits die vollständige Struktur lib/plugins/<kennung>/ und wird von Hand entpackt (Weg C).

Schritt 2: Installieren

Ein Paket aus dem Baukasten wird entpackt — Weg C. Es enthält bereits die Struktur lib/plugins/… und lib/tpl/… für alle enthaltenen Komponenten; Sie legen den Inhalt über Ihre Instanz und sind fertig. Die Wege A und B nehmen jeweils eine Komponente und sind für den Bezug einzelner Pakete gedacht.

Nehmen Sie A, wenn Sie am Bildschirm eine einzelne Komponente nachziehen, B für mehrere hintereinander auf der Kommandozeile, C für ein Paket und immer dann, wenn der Webserver nicht in lib/plugins/ schreiben darf.

Weg A: Erweiterungsmanager

Melden Sie sich als Administrator an und öffnen Sie Administration → Erweiterungsverwaltung. Adresse: ?do=admin&page=extension
Wechseln Sie auf den Reiter Manuell installieren.
Laden Sie die ZIP-Datei hoch — oder tragen Sie unter Download-URL eine Adresse ein, die der Server ohne Anmeldung abrufen kann. Eine tokenpflichtige Adresse funktioniert hier nicht; laden Sie in diesem Fall die Datei hoch.
Bestätigen Sie mit Installieren.

Weg B: Kommandozeile

Aus dem Wurzelverzeichnis der DokuWiki-Instanz, mit demselben Benutzerkonto, unter dem der Webserver läuft — sonst gehören die neuen Dateien dem falschen Konto:

php bin/plugin.php extension install <url-oder-name>
php bin/plugin.php extension list -f i

Der zweite Aufruf listet die installierten Erweiterungen und ist zugleich die erste Funktionsprüfung.

Weg C: Von Hand

Ein Paket aus dem Baukasten:

Prüfen Sie das Archiv gegen seine Prüfsummen: sha256sum -c checksums.sha256 im entpackten Verzeichnis. Unter Windows: Get-FileHash je Datei oder das mitgelieferte manifest.json als Beleg dessen, was enthalten sein sollte.
Legen Sie lib/plugins/ und lib/tpl/ aus dem Archiv über die gleichnamigen Verzeichnisse Ihrer Instanz. Die Verzeichnisnamen sind bereits richtig; der Baukasten hat sie erzeugt und vor dem Packen geprüft.
Setzen Sie Eigentümer und Rechte so, dass der Webserver lesen darf.
Die Reihenfolge in der README.txt betrifft die Inbetriebnahme, nicht das Kopieren: Kopieren Sie alles, und arbeiten Sie die Erstkonfiguration in der genannten Reihenfolge ab.

Eine einzelne Komponente:

Entpacken Sie das Paket.
Legen Sie den Inhalt nach lib/plugins/<kennung>/ — bei einem Template nach lib/tpl/<kennung>/. Der Verzeichnisname muss exakt dem Feld base aus plugin.info.txt bzw. template.info.txt entsprechen.
Setzen Sie Eigentümer und Rechte so, dass der Webserver lesen darf.

Ein abweichender Verzeichnisname ist der häufigste Installationsfehler und der am schwersten zu erkennende. DokuWiki lädt Komponenten über den Verzeichnisnamen; heißt das Verzeichnis wkcore-main statt wkcore, erscheint die Komponente zwar im Erweiterungsmanager, aber keine ihrer Klassen wird je geladen und keine ihrer Dienste je angemeldet. Es gibt keine Fehlermeldung — nur ein Merkmal, das nicht da ist.

Genau deshalb prüft der Baukasten vor dem Packen je Komponente, ob das Feld base zum Verzeichnisnamen passt, und bricht ab, wenn es das nicht tut. Ein Paket aus dieser Quelle kann diesen Fehler nicht enthalten.

Schritt 3: Die Aktivierung prüfen

DokuWiki aktiviert eine neu installierte Komponente von sich aus; conf/plugins.local.php bekommt nur dann einen Eintrag, wenn Sie vom Standard abweichen. Prüfen Sie trotzdem, dass keine Voreinstellung dagegen steht — Einzelheiten unter Eine Komponente aktivieren oder deaktivieren.

Schritt 4: Erstkonfiguration

Öffnen Sie Administration → Konfiguration (?do=admin&page=config). Jede Komponente mit Einstellungen hat dort einen eigenen Abschnitt, benannt nach ihrer Kennung.

Für die Mehrzahl der Komponenten ist hier nichts zu tun: Die Voreinstellungen sind so gewählt, dass die Komponente nach der Installation bereits das tut, wofür es sie gibt. Vier Komponenten sind die Ausnahme, und bei dreien davon ist das Absicht — sie gewähren nach der Installation bewusst noch nichts:

Komponente	Was Sie vor der ersten Benutzung setzen müssen	Was sonst passiert
`wkdoado`	`ado_host_allow`	Die Liste erlaubter Hosts ist leer, und eine leere Liste erlaubt keine Anfrage.
`wkdogit`	`git_binary` (absoluter Pfad), `git_repo_root`	Ohne `git_repo_root` fehlt die Schranke, die entscheidet, ob „ein Repository-Pfad“ einen der Ihren meint oder irgendeinen Pfad der Maschine.
`wkdocore`	`projectroot`	Diese eine Einstellung entscheidet, was als Projekt zählt. Eine spätere Änderung ordnet alles auf einmal neu — setzen Sie sie, bevor Inhalte entstehen.
`wkmail`	`host`, `port`, `encryption`, `username`, `password`, `mailfrom`	Ohne Zugangsdaten bleibt der Versand beim PHP-eigenen `mail()`.
`wkbizway` (Template)	`template` in der DokuWiki-Konfiguration auf `wkbizway` setzen	Ein Template wird nicht aktiviert, sondern ausgewählt.

Die vollständige Aufstellung der Einstellungen je Komponente steht in der Tabelle zur Erstkonfiguration.

Ergebnis prüfen

Eine Installation ist nicht abgeschlossen, weil Dateien im Verzeichnis liegen. Sie ist abgeschlossen, wenn diese drei Nachweise gelingen — in dieser Reihenfolge, weil jeder den vorigen voraussetzt.

1. DokuWiki hat das Manifest gelesen. Öffnen Sie Administration → Erweiterungsverwaltung → Installierte Erweiterungen. Die Komponente steht dort mit Namen, Autor und Datum. Zeigt die Liste nur den Verzeichnisnamen, wurde plugin.info.txt nicht gefunden — der Verzeichnisname weicht ab oder das Paket ist unvollständig.

Auf der Kommandozeile:

php bin/plugin.php extension list -f i

2. Der Programmcode wird geladen. Setzen Sie $conf['allowdebug'] = 1 in der Konfiguration und rufen Sie ?do=wkcore_diag auf. Die Seite listet die angemeldeten Dienste und die Ereignisse der Plattform. Eine speichernde Komponente muss hier mit ihrem Dienst auftauchen; steht sie nicht in der Liste, ist ihr Programmcode nicht gelaufen, gleichgültig was der Erweiterungsmanager anzeigt.

Schalten Sie allowdebug danach wieder ab. Die Diagnoseseiten sind genau durch diese Einstellung geschützt.

3. Die Komponente tut ihre Arbeit. Das Zeichen dafür ist je Komponente ein anderes: ein Eintrag im Administrationsmenü, eine Auszeichnung, die auf einer Seite etwas rendert, oder ein Kommandozeilenbefehl. Die Tabelle zur Funktionsprüfung nennt je Komponente genau eines — und zwar eines, das eine andere Ursache ausschließt: Ein Menüeintrag beweist, dass die Komponente geladen wurde; erst eine Auszeichnung, die etwas rendert, beweist, dass sie auch arbeitet.

Beispiel für wkcore, wkstorage und wkrequest gemeinsam: Öffnen Sie Administration. Der Eintrag Administrative Anfragen steht dort genau dann, wenn wkrequest geladen ist; er öffnet einen Posteingang genau dann, wenn wkcore den Dienst storage.sqlite vermittelt hat und wkstorage die Datei data/dwdo/request.sqlite anlegen konnte. Existiert diese Datei nach dem ersten Aufruf, haben alle drei Komponenten zusammengearbeitet.

Nächste Schritte

Komponentenmatrix — was für Ihre Komponente im Einzelnen gilt.
How to: Eine Komponente aktivieren oder deaktivieren — wenn Sie eine installierte Komponente vorübergehend stilllegen wollen.
Eine Komponente aktualisieren — der Weg für die nächste Fassung.
Fehlerdiagnose — wenn einer der drei Nachweise misslingt.
Erweiterungen dieses Hauses — die eigene Dokumentation jeder Komponente, mit Schnelleinstieg und Tutorial.