# Manage

Update- und Backup-Server für PHP-Projekte, plus ein weitergebbares Client-Paket.

## Zweck

Mehrere eigenständige PHP-Projekte brauchen dieselben zwei Dinge: eine Möglichkeit,
neue Versionen einzuspielen, und regelmäßige Sicherungen der Betriebsdaten. `manage`
stellt beides zentral bereit, statt es in jedem Projekt erneut zu bauen.

Eine Installation betreut **ein Produkt** mit einer überschaubaren Zahl von
Instanzen. Für ein weiteres Produkt wird `manage` erneut ausgerollt.

## Kernfunktionen

- Release-Verwaltung: Pakete hochladen, Prüfsummen serverseitig berechnen, aktuelles
  Release festlegen
- Backup-Empfang je Instanz, mit zwei Aufbewahrungsstufen und optionalem S3-Archiv
- Instanzregister mit Token-Authentifizierung, Deaktivierung und Token-Erneuerung
- Übersicht über installierte Versionen, letzte Sicherungen und offene Migrationen
- Client-Paket mit Kommandozeile, fertiger Adminoberfläche und Funktions-API

## Voraussetzungen

- PHP 8.x
- ein Webserver (Apache mit aktiver `.htaccess` oder nginx mit gesetzten Sperren)
- Schreibrechte auf `storage/`

Keine Datenbank, kein Composer, kein Build-Schritt, keine externen Bibliotheken.

## Wichtige Dateien

- Konfiguration: `config.php` (aus `config.sample.php`)
- Oberfläche: `admin/`
- Schnittstelle für Clients: `api/v1/`
- Gemeinsame Bibliothek: `includes/`
- Zustand: `storage/` (nicht öffentlich)
- Weitergebbares Client-Paket: `client-package/`

## Einrichtung

1. `config.sample.php` nach `config.php` kopieren.
2. Passwort-Hash erzeugen und als `MANAGE_ADMIN_PASSWORD_HASH` eintragen:
   `php -r 'echo password_hash("…", PASSWORD_DEFAULT), PHP_EOL;'`
3. `MANAGE_PUBLIC_URL` auf die absolute Adresse dieser Installation setzen.
4. `MANAGE_PRODUCT_NAME` und `MANAGE_PACKAGE_PREFIX` auf das betreute Produkt setzen.
5. Schreibrechte auf `storage/` sicherstellen.
6. `admin/login.php` öffnen und unter **Einstellungen → Diagnose** prüfen, dass alles
   Wesentliche stimmt.

Ausführlich: [docs/SERVER_SETUP.md](docs/SERVER_SETUP.md).

## Ein Projekt anbinden

1. Im Manage-Server unter **Instanzen** eine Instanz anlegen und das einmalig
   angezeigte Token notieren.
2. Client-Paket bauen und übergeben:
   `./scripts/build-client-package.sh --server-url https://manage.example.org`
3. Im Projekt: `manage-client/` einkopieren, `config.php` anlegen,
   `php manage-client/bin/manage-client.php status` ausführen.

Die vollständige Anleitung dafür liegt **im Paket selbst**
([client-package/README.md](client-package/README.md)), damit die empfangende Seite
keinen Zugriff auf dieses Repository braucht.

## Dokumentation

Serverseitig, in `docs/`:

- [ARCHITECTURE.md](docs/ARCHITECTURE.md) – Aufbau, Datenfluss, Speicherformate
- [SERVER_SETUP.md](docs/SERVER_SETUP.md) – Installation, Webserver, Limits, S3
- [INSTANCE_MANAGEMENT.md](docs/INSTANCE_MANAGEMENT.md) – Instanzen, Tokens, Übergabe des Client-Pakets
- [RELEASING.md](docs/RELEASING.md) – Pakete bauen und veröffentlichen
- [CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md) – alle Serverkonstanten

Für Projekte, in `client-package/docs/`: Quickstart, Integration, Konfiguration,
Funktions-API, Backup-Quellen, Paketbau, Post-Update-Hooks, Protokoll, Fehlersuche,
Sicherheit.

Im Browser lesbar über `docs/index.php` beziehungsweise `client-package/docs/index.php`
(Markdown wird mit dem mitgelieferten [marked](https://marked.js.org/) gerendert).

### Öffentliches Client-Handbuch

`client-docs/` veröffentlicht den Inhalt von `client-package/` über HTTP: jedes Kapitel
und jede Quelldatei als eigene Seite, dazu die Schnittstelle als OpenAPI. Anders als
`admin/` und `api/v1/` ist dieser Ordner ohne Anmeldung erreichbar – er ist dafür da,
weitergegeben zu werden, damit ein Projekt eingebunden werden kann, ohne vorher ein ZIP
zu verschicken.

| Adresse | Inhalt |
|---|---|
| `client-docs/` | Übersicht, von dort ein Kapitel oder eine Quelldatei |
| `client-docs/index.php?doc=01_QUICKSTART` | ein Kapitel |
| `client-docs/index.php?code=manage-client/lib/updater.php` | eine Quelldatei |
| `client-docs/api.php` | Protokoll v1 in Swagger UI |
| `client-docs/openapi.php` | das OpenAPI-Dokument allein, für Codegeneratoren |

Für Programme gibt es dieselben Seiten als reines Markdown unter `llms.php`, mit
`llms.php?doc=…` und `llms.php?code=…` daneben. `client-docs/llms.php` ist das
Verzeichnis: es nennt jede Seite mit einem Satz Beschreibung und ihrer Größe und führt
für die üblichen Aufgaben – Client einbauen, nur Backups, nur Updater, eigenen Client
schreiben, Fehlersuche – die kurze Liste der Seiten auf, die dafür reicht. Das ist der
Zweck der Aufteilung: nur laden, was gebraucht wird. Diese Adresse bekommt ein LLM.
Apache beantwortet zusätzlich `llms.txt`; kanonisch ist `llms.php`, weil das ohne
`mod_rewrite` auskommt.

Die Seiten für Menschen rendern ihr Markdown im Browser und tragen im Quelltext einen
Kommentar und ein unsichtbares Element, die auf die Markdown-Fassung derselben Seite
verweisen – ein Programm, das versehentlich dort landet, findet den Weg.

Der Inhalt wird bei jedem Aufruf aus `client-package/` gelesen; es gibt nichts zu bauen
und nichts nachzuziehen. `manage-client/config.php` ist von der Veröffentlichung
ausgenommen, damit ein lokal angelegtes Token nicht öffentlich wird.

marked und Swagger UI liegen unter `client-docs/assets/` im Repository. Es wird kein
fremder Server kontaktiert, auch nicht für Schriften oder Symbole.

## Was bewusst fehlt

- **Keine Wiederherstellung.** Backups werden erstellt, übertragen und zum Download
  bereitgestellt, aber nie automatisch zurückgespielt. Ein Update sichert die
  überschriebenen Dateien, kann sie aber nicht zurückholen.
- **Keine automatischen Updates.** Der Server bietet an, die Instanz entscheidet.
- **Keine Signatur der Pakete.** Prüfsumme und Paket kommen vom selben Server; die
  Absicherung ist TLS plus Token. Der Manage-Server muss entsprechend geschützt sein.
- **Keine Kanäle pro Instanz.** Es gibt ein aktuelles Release für alle Instanzen
  eines Servers.

## Hinweise

- Kein automatisiertes Test-/CI-Setup vorgesehen.