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 gesamten Inhalt von client-package/ als eine Seite: alle Kapitel, den vollständigen Quellcode und 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/	das Handbuch, zum Lesen
client-docs/llms.txt	dasselbe als reiner Text – diese Adresse bekommt ein LLM
client-docs/api.php	Protokoll v1 in Swagger UI
client-docs/openapi.php	das OpenAPI-Dokument allein, für Codegeneratoren

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.