# Instanzen verwalten

## Überblick

Eine Instanz ist eine Installation des betreuten Produkts – etwa "Produktiv",
"Test" oder die Installation eines bestimmten Kunden. Jede Instanz hat eine
Kennung und ein geheimes Token.

Alles dazu unter **Instanzen** in der Oberfläche.

## Instanz anlegen

1. **Instanzen** öffnen, Kennung eintragen, optional Bezeichnung und Notiz.
2. Anlegen. Direkt danach wird das Token angezeigt – **einmalig**, zusammen mit
   einem fertigen Konfigurationsblock zum Kopieren.
3. Den Block in die `manage-client/config.php` der Instanz eintragen.

Kennungen dürfen Buchstaben, Zahlen, Punkt, Unterstrich und Bindestrich enthalten,
müssen mit einem Buchstaben oder einer Zahl beginnen und höchstens 120 Zeichen lang
sein. Sie erscheinen im Dateipfad der Backups; sprechende Namen wie `example-prod` und
`example-test` zahlen sich aus.

## Das Token

- 32 zufällige Bytes, als 64 Hex-Zeichen dargestellt.
- Der Server speichert nur den SHA-256-Hash. Es gibt keinen Weg, ein Token später
  wieder anzuzeigen.
- Geht es verloren, wird ein neues erzeugt – das alte wird dabei sofort ungültig.

Mit dem Token kann eine Instanz Releases herunterladen und Backups hochladen. Sie
kann **nicht** Backups herunterladen und **nicht** Releases verändern; beides
erfordert die Anmeldung an der Oberfläche.

### Token erneuern

**Instanzen → Token erneuern**. Das alte Token verliert sofort seine Gültigkeit;
die Instanz meldet danach `Authentifizierung fehlgeschlagen`, bis das neue Token
eingetragen ist. Kurze Ausfälle von Cron-Jobs sind also einzuplanen.

Anlässe: Verdacht auf Kompromittierung, Personalwechsel, Übergabe eines Projekts.

## Deaktivieren statt löschen

**Deaktivieren** lässt die Instanz bestehen, weist aber jede API-Anfrage mit `403`
ab. Der richtige Weg, wenn eine Installation vorübergehend stillgelegt wird oder
etwas unklar ist – das Token bleibt gültig und die Instanz ist mit einem Klick
wieder betriebsbereit.

**Entfernen** löscht den Registereintrag. Die gespeicherten Backups bleiben
erhalten und unter **Backups** sichtbar und herunterladbar; sie werden dort als
"nicht mehr registriert" gekennzeichnet. Neue Uploads sind nicht mehr möglich.

## Statusanzeige

Die Übersicht zeigt für jede Instanz:

| Feld | Herkunft |
|---|---|
| Status | `aktiv`, `inaktiv` (länger als 7 Tage nicht gesehen) oder `deaktiviert` |
| Version | letzte Meldung der Instanz |
| Update | Vergleich dieser Version mit dem aktuellen Release |
| Zuletzt gesehen | jede authentifizierte Anfrage aktualisiert diesen Wert |
| Letztes Backup | Zeitpunkt des letzten empfangenen Backups |
| Offene Migrationen | aus dem Heartbeat der Instanz |

`inaktiv` bei einer laufenden Installation bedeutet meist, dass der Cron-Job für
den Heartbeat nicht läuft. Ohne Cron meldet sich eine Instanz nur, wenn jemand die
Oberfläche im Projekt benutzt.

Offene Migrationen sind das wichtigste Warnsignal: Sie bedeuten, dass ein Update
zwar ausgerollt wurde, ein Teil des Post-Update-Schritts aber fehlgeschlagen ist.

## Client-Paket übergeben

Der Ordner `client-package/` enthält den Client **und** dessen vollständige
Dokumentation. Zum Weitergeben:

```bash
./scripts/build-client-package.sh --server-url https://manage.example.org
```

Das Ergebnis liegt unter `build/manage-client-<datum>.zip`. Mit `--server-url` ist
die Server-Adresse in der mitgelieferten `config.sample.php` bereits eingetragen;
die empfangende Seite ergänzt nur noch Kennung und Token.

Das Skript entfernt vor dem Packen jede `config.php` und alle Protokolldateien,
damit kein Token aus einer Testinstallation mitgeliefert wird.

## Mehrere Umgebungen

Übliches Vorgehen für ein Produkt mit Test- und Produktivsystem:

| Instanz | Zweck |
|---|---|
| `produkt-test` | bekommt neue Releases zuerst |
| `produkt-prod` | folgt nach erfolgreichem Test |

Beide holen sich dasselbe `latest`. Wer ein Release nur auf dem Testsystem haben
will, veröffentlicht es und setzt vorübergehend das ältere wieder als aktuell –
oder rollt auf dem Testsystem mit `update --force` gezielt aus. Getrennte Kanäle
pro Instanz gibt es bewusst nicht; dafür wird ein zweiter Manage-Server ausgerollt.

## Weiter

- [SERVER_SETUP](SERVER_SETUP.md) – Installation
- [RELEASING](RELEASING.md) – Releases veröffentlichen
- [../client-package/docs/08_PROTOCOL.md](../client-package/docs/08_PROTOCOL.md) – Authentifizierung im Detail