# 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).

## 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.