manager

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.

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), damit die empfangende Seite keinen Zugriff auf dieses Repository braucht.

Dokumentation

Serverseitig, in docs/:

• ARCHITECTURE.md – Aufbau, Datenfluss, Speicherformate
• SERVER_SETUP.md – Installation, Webserver, Limits, S3
• INSTANCE_MANAGEMENT.md – Instanzen, Tokens, Übergabe des Client-Pakets
• RELEASING.md – Pakete bauen und veröffentlichen
• 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 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.