# PmWiki-Neuinstallation und Grundbetrieb

## Zweck

Dieser Leitfaden beschreibt eine allgemeine, sichere PmWiki-Neuinstallation
für ein Projekt, in dem Menschen und begrenzte KI-Agenten zusammenarbeiten.
Er ist nicht für tägliche Seitenänderungen gedacht. Dafür gilt
`PmWiki_Seitenupdates.md`.

Die jeweils aktuelle offizielle PmWiki-Dokumentation hat bei Versions- und
Systemfragen Vorrang.

## 1. Voraussetzungen

- unterstützte PHP-Version,
- Webserver mit HTTPS,
- Schreibrechte nur dort, wo PmWiki sie benötigt,
- lokaler oder serverseitiger Backupweg,
- getrennte Konten für Administration, Herausgeber und Agenten,
- sichere Ablage für Zugangsdaten außerhalb des Webroots und der Dokumentation.

Vor Beginn prüfen:

- https://www.pmwiki.org/wiki/PmWiki/Requirements
- https://www.pmwiki.org/wiki/PmWiki/ReleaseNotes
- https://www.pmwiki.org/wiki/PmWiki/Security

## 2. Installationsprinzip

1. Aktuelle stabile PmWiki-Version von der offiziellen Quelle beziehen.
2. Prüfsumme oder Signatur kontrollieren, sofern angeboten.
3. Archiv in ein vorbereitetes Webverzeichnis entpacken.
4. HTTPS und sichere PHP-/Webserver-Einstellungen aktivieren.
5. PmWiki einmal aufrufen und die Erzeugung der Arbeitsverzeichnisse prüfen.
6. Eigene Einstellungen ausschließlich in `local/`, `cookbook/`, `pub/skins/`
   und `pub/css/` anlegen.
7. Erst einen kleinen Pilotbereich einrichten und testen.

Der PmWiki-Core bleibt unverändert. Dadurch bleiben Updates, Vergleiche und
Wiederherstellung beherrschbar.

## 3. Typische Verzeichnisstruktur

```text
pmwiki.php             Programmstart
scripts/               PmWiki-Core
wikilib.d/             mitgelieferte Seiten
wiki.d/                Laufzeitdaten und Seitenhistorie
local/                 lokale Konfiguration
cookbook/              zusätzliche Rezepte
pub/skins/             eigene Skins
pub/css/               zusätzliche Stylesheets
uploads/               Anhänge
```

`wiki.d/` ist kein gewöhnlicher Markdown-Bestand. Direkte Änderungen sind nur
für kontrollierte Migration oder Wiederherstellung zulässig.

## 4. Lokale Konfiguration

Projektanpassungen beginnen in `local/config.php` oder gezielt in gruppen- und
seitenspezifischen Konfigurationsdateien.

Grundsätze:

- PHP-Dateien beginnen mit `<?php` und benötigen kein schließendes `?>`.
- Keine erfundenen PmWiki-Variablen verwenden; vorhandene API dokumentieren.
- Rezepte mit `include_once()` laden.
- Ausführbaren Fremdcode vor Installation lesen und Herkunft dokumentieren.
- Konfiguration klein halten und thematisch auf Dateien verteilen.
- Fehlermeldungen nicht öffentlich anzeigen; Diagnose nur kontrolliert nutzen.

Offizielle Referenz:

- https://www.pmwiki.org/wiki/PmWiki/LocalCustomizations
- https://www.pmwiki.org/wiki/PmWiki/Variables

## 5. Konten und Rechte

Empfohlenes Rollenmodell:

- Administrator: technische Konfiguration und Notfälle,
- Herausgeber: Inhalte prüfen und freigeben,
- Agent: lesen, bearbeiten und zur Prüfung einreichen,
- Öffentlichkeit: nur freigegebene Bereiche lesen.

Ein Agent benötigt normalerweise keine Administratorrechte. Das Prinzip der
geringsten Berechtigung begrenzt Bedienfehler und Sicherheitsfolgen.

Getrennt schützen:

- Lesen,
- Bearbeiten,
- Upload,
- administrative Aktionen,
- Backup und Wiederherstellung.

Referenz: https://www.pmwiki.org/wiki/PmWiki/AuthUser

## 6. Öffentliche und geschützte Gruppen

Öffentliche Inhalte, technische Seiten und eine geschützte Werkstatt werden in
getrennten Wiki-Gruppen geführt. Gruppen können eigene Sidebars,
Zugriffsregeln, Kopf- und Fußbereiche sowie lokale Konfiguration erhalten.

Für ein Agentenprojekt sind mindestens sinnvoll:

- öffentliche Inhaltsgruppen,
- eine geschützte Arbeitsgruppe,
- technische Standardgruppen `Site` und `SiteAdmin`,
- ein klarer Status- und Freigabeprozess.

Technische Standardgruppen werden nicht für normale redaktionelle Inhalte
verwendet.

## 7. Status- und Reviewmodell

Ein einfaches Schema:

```text
draft → review → approved → revision → approved
```

Die Freigabe bleibt einer namentlich verantwortlichen Person vorbehalten.
Statuswerte werden als PageTextVariables gespeichert und können für
Aufgabenlisten, Darstellung und Robots-Regeln ausgewertet werden.

Beispiel:

```text
(:PageType:article:)
(:Status:draft:)
(:Responsible:Name:)
(:CreatedBy:agent:)
(:CreatedDate:2026-09-29:)
```

Referenz: https://www.pmwiki.org/wiki/PmWiki/PageTextVariables

## 8. Sichere Schreibschnittstelle für Agenten

Für kleine und mittlere Projekte kann die normale Bearbeitungsoberfläche als
kontrollierte Schreibschnittstelle dienen:

1. Agent meldet sich mit begrenztem Konto an.
2. Bearbeitungsformular und aktueller Quelltext werden abgerufen.
3. CSRF-Token, Basistimestamp und Live-Hash werden übernommen.
4. Änderung wird auf der aktuellen Live-Fassung aufgebaut.
5. Autor und Änderungszusammenfassung werden mitgesendet.
6. Gespeicherter Quelltext wird erneut abgerufen und verglichen.
7. Öffentliche Darstellung und Status werden geprüft.

Zusätzlich ist eine semantische Verlustprüfung nötig. Ein Hash verhindert
keinen Verlust vorhandener Metadaten oder menschlicher Ergänzungen, wenn eine
veraltete lokale Komplettfassung gespeichert wird.

## 9. Uploads absichern

- Uploadrecht auf notwendige Rollen begrenzen.
- Erlaubte Dateitypen positiv auflisten.
- Dateigrößen begrenzen.
- Skriptausführung im Uploadverzeichnis verhindern.
- MIME-Typ und Dateiendung prüfen.
- Vorhandene Dateien nicht still überschreiben.
- Fremdrechte, Lizenz und Herkunft dokumentieren.
- Uploads in Backups und Wiederherstellungstests berücksichtigen.

Referenz: https://www.pmwiki.org/wiki/PmWiki/UploadsAdmin

## 10. Skin und Darstellung

- Eigenen Skin oder lokale CSS-Anpassungen verwenden.
- Template-Marker und Standardaktionen beibehalten, solange kein begründeter
  Ersatz existiert.
- Titel, H1, Canonical, Robots und Navigation zentral erzeugen.
- Mobile Darstellung, Tastaturbedienung, Kontrast und Alternativtexte prüfen.
- Nach CSS-Änderungen Cache-Versionen kontrolliert erhöhen.

Der Skin darf redaktionelle Zustände sichtbar machen, aber nicht selbst die
Freigabeentscheidung ersetzen.

Referenz: https://www.pmwiki.org/wiki/PmWiki/Skins

## 11. Eigene Markups und Cookbook-Rezepte

Eigene Erweiterungen sind ausführbarer Code und werden wie Software behandelt:

- kleinstmöglicher Funktionsumfang,
- eindeutige interne Namen,
- dokumentierte Eingaben und Ausgaben,
- sichere HTML-Kodierung,
- keine beliebige PHP-, HTML- oder JavaScript-Ausführung für normale Editoren,
- Berechtigungsprüfung bei schreibenden Aktionen,
- CSRF-Schutz,
- Tests für Erfolg, Fehler und unberechtigten Zugriff.

Cookbook-Rezepte nur aus vertrauenswürdiger Quelle und nach Quellprüfung
verwenden.

Referenzen:

- https://www.pmwiki.org/wiki/PmWiki/CustomMarkup
- https://www.pmwiki.org/wiki/Cookbook/CookbookBasics

## 12. Suchmaschinen und Datenschutz

- Nur ausdrücklich öffentliche und freigegebene Inhalte indexieren.
- Entwürfe, Prüfungen, Überarbeitungen, technische Aktionen und geschützte
  Gruppen erhalten `noindex,nofollow,noarchive`.
- Sitemap nur mit öffentlichen Inhaltsseiten erzeugen.
- Besucherkommentare und persönliche Daten gesondert behandeln.
- Statistiken datensparsam und ohne unnötige Rohdaten führen.
- Robots-Regeln zentral ableiten statt auf vielen Seiten zu duplizieren.

## 13. Backups und Wiederherstellung

Sichern:

- `wiki.d`,
- `uploads`,
- `local`,
- `cookbook`,
- eigener Skin und CSS,
- Manifeste und projektspezifische Werkzeuge.

Secrets und passworthaltige Archive bleiben geschützt. Backups werden
versioniert und nicht still überschrieben.

Mindestens einmal auf einer getrennten Testinstallation prüfen:

1. Dateien wiederherstellen,
2. Rechte setzen,
3. Anmeldung testen,
4. öffentliche und geschützte Seiten prüfen,
5. Uploads öffnen,
6. Seitenhistorie und Freigabestatus kontrollieren.

Referenz: https://www.pmwiki.org/wiki/PmWiki/BackupAndRestore

## 14. Updates

Vor einem PmWiki- oder PHP-Update:

1. Release Notes und Anforderungen lesen.
2. Vollständigen Rücksetzpunkt erstellen.
3. lokale Anpassungen und Rezepte inventarisieren.
4. Update in einer Testinstallation durchführen.
5. PHP-Lint und HTTP-Tests ausführen.
6. Anmeldung, Bearbeiten, Speichern, Upload, Suche, Historie und Freigabe testen.
7. Erst danach Produktion aktualisieren.

Core-Dateien werden ersetzt, lokale Anpassungen bleiben getrennt. Eigene
Core-Patches erschweren diesen Vorgang und sollen vermieden werden.

Referenz: https://www.pmwiki.org/wiki/PmWiki/Upgrades

## 15. Abnahmecheck einer Neuinstallation

```text
[ ] HTTPS aktiv
[ ] unterstützte PHP- und PmWiki-Version
[ ] Core unverändert
[ ] lokale Konfiguration getrennt
[ ] Rollen und Rechte getestet
[ ] Werkstatt geschützt
[ ] Agentenkonto minimal berechtigt
[ ] Status- und Reviewmodell funktionsfähig
[ ] Uploadtypen und Skriptausführung abgesichert
[ ] sichere Cookies und Security-Header geprüft
[ ] Titel, Canonical und Robots korrekt
[ ] Sitemap enthält nur vorgesehene Inhalte
[ ] Backup erstellt
[ ] Wiederherstellung getestet
[ ] Bearbeitungs- und Konfliktprüfung erfolgreich
[ ] Desktop- und Mobilansicht geprüft
```

## 16. Weiterführende offizielle Dokumentation

- https://www.pmwiki.org/wiki/PmWiki/DocumentationIndex
- https://www.pmwiki.org/wiki/PmWiki/Requirements
- https://www.pmwiki.org/wiki/PmWiki/Security
- https://www.pmwiki.org/wiki/PmWiki/InitialSetupTasks
- https://www.pmwiki.org/wiki/PmWiki/AuthUser
- https://www.pmwiki.org/wiki/PmWiki/LocalCustomizations
- https://www.pmwiki.org/wiki/PmWiki/UploadsAdmin
- https://www.pmwiki.org/wiki/PmWiki/BackupAndRestore
- https://www.pmwiki.org/wiki/PmWiki/Upgrades