# Server einrichten

## Überblick

Installation und Betrieb des Manage-Servers. Voraussetzungen: PHP 8.0 oder neuer
und ein Webserver. Kein Datenbankserver, kein Composer, kein Build-Schritt.

## Installation

1. Repository in ein Verzeichnis des Webservers legen, zum Beispiel
   `/var/www/manage`.

2. Konfiguration anlegen:

   ```bash
   cp config.sample.php config.php
   ```

3. Passwort-Hash erzeugen und eintragen:

   ```bash
   php -r 'echo password_hash("ein-langes-passwort", PASSWORD_DEFAULT), PHP_EOL;'
   ```

   ```php
   define("MANAGE_ADMIN_PASSWORD_HASH", '$2y$12$…');
   ```

   Einfache Anführungszeichen verwenden – ein bcrypt-Hash enthält `$`.

4. Öffentliche URL setzen. Ohne diesen Wert kann kein Client ein Paket
   herunterladen:

   ```php
   define("MANAGE_PUBLIC_URL", "https://manage.example.org");
   ```

   Absolut, ohne Schrägstrich am Ende. Liegt die Installation in einem
   Unterverzeichnis, gehört es dazu: `https://example.org/manage`.

5. Produkt benennen. `MANAGE_PACKAGE_PREFIX` bestimmt den Dateinamen der
   gespeicherten Pakete und sollte zum Build-Skript des Projekts passen:

   ```php
   define("MANAGE_PRODUCT_NAME", "Example Orderform");
   define("MANAGE_PACKAGE_PREFIX", "example-orderform");
   ```

6. Schreibrechte auf `storage/` sicherstellen. Das Verzeichnis wird bei Bedarf
   selbst angelegt:

   ```bash
   mkdir -p storage && chown www-data:www-data storage && chmod 2775 storage
   ```

7. Oberfläche öffnen: `https://manage.example.org/admin/login.php`.

Unter **Einstellungen → Diagnose** steht danach, ob alles Wesentliche stimmt:
öffentliche URL, Schreibrechte, Passwort, Upload-Limits.

## Webserver

### Apache

Die mitgelieferte `.htaccess` sperrt `storage/`, `includes/`, `client-package/`
sowie `config.php` und setzt Sicherheits-Header. Sie funktioniert nur, wenn
`AllowOverride All` für das Verzeichnis gesetzt ist.

### nginx

Für nginx greift keine `.htaccess`. Die Sperren müssen von Hand gesetzt werden:

```nginx
location ^~ /storage/       { deny all; return 404; }
location ^~ /includes/      { deny all; return 404; }
location ^~ /client-package/ { deny all; return 404; }
location = /config.php      { deny all; return 404; }
location ~ /\.              { deny all; return 404; }
```

Prüfen, dass die Sperren greifen:

```bash
curl -s -o /dev/null -w "%{http_code}\n" https://manage.example.org/config.php
curl -s -o /dev/null -w "%{http_code}\n" https://manage.example.org/storage/instances.json
```

Beides muss `403` oder `404` liefern.

## Upload-Limits

Backups und Release-Pakete werden per HTTP hochgeladen. Beide PHP-Grenzen müssen
groß genug sein, `post_max_size` mindestens so groß wie `upload_max_filesize`:

```ini
upload_max_filesize = 256M
post_max_size = 256M
max_execution_time = 300
memory_limit = 256M
```

Die aktuellen Werte zeigt die Diagnose-Seite. Ist der Wert zu klein, meldet der
Client eine Fehlermeldung, die die Ursache ausdrücklich benennt.

`memory_limit` wird relevant, wenn das S3-Archiv aktiv ist: Ein Upload zu S3 hält
die Datei vollständig im Speicher.

## Aufbewahrung

Unter **Einstellungen** einstellbar, gespeichert in `storage/settings.json`. Die
Werte dort haben Vorrang vor den Konstanten in `config.php`.

- **Lokale Backups pro Instanz** – Standard 30, Minimum 1
- **S3-Backups pro Instanz** – Standard 365, nur bei aktivem S3-Archiv

Änderungen werden sofort angewendet, nicht erst beim nächsten Upload.

## S3-Archiv (optional)

Ohne S3 liegen alle Backups auf der lokalen Platte. Mit S3 wird jedes empfangene
Backup zusätzlich in ein S3-kompatibles Objektspeicher-System geschoben; lokal
bleiben nur die neuesten Kopien.

```php
define("MANAGE_S3_ENABLED", true);
define("MANAGE_S3_ENDPOINT", "https://fsn1.your-objectstorage.com");
define("MANAGE_S3_REGION", "fsn1");
define("MANAGE_S3_BUCKET", "mein-backup-bucket");
define("MANAGE_S3_PREFIX", "manage-backups");
define("MANAGE_S3_ACCESS_KEY", "…");
define("MANAGE_S3_SECRET_KEY", "…");
```

Objekte liegen unter `<prefix>/<instanz>/<dateiname>`.

Adressierung: Standard ist virtual-hosted (`https://<bucket>.<endpoint>/<key>`),
was Hetzner und die meisten Anbieter erwarten. Verlangt der Anbieter path-style,
`MANAGE_S3_PATH_STYLE` auf `true` setzen.

Verhalten:

- S3-Fehler lassen einen Client-Upload nie fehlschlagen.
- Eine lokale Kopie wird erst gelöscht, wenn sie aus der lokalen Aufbewahrung
  gefallen **und** die S3-Kopie bestätigt ist.
- Fehlgeschlagene Uploads werden beim nächsten Upload derselben Instanz oder über
  "S3-Uploads jetzt nachholen" wiederholt.
- Der Bucket kann und soll privat bleiben: Downloads laufen über die Oberfläche.
- Beim Aktivieren auf einer bestehenden Installation einmal "S3-Uploads jetzt
  nachholen" drücken, damit das Archiv aufgeholt wird.

Fehlersuche über `storage/logs/s3.log` und den Auszug unter **Einstellungen**:
`AccessDenied` oder eine Umleitung in der Statuskette deuten fast immer auf die
falsche Adressierungsart hin, `SignatureDoesNotMatch` auf falsche Region oder
falschen Secret Key. Umleitungen werden bewusst nicht verfolgt, damit eine
Fehlkonfiguration sichtbar wird.

## Sicherung des Servers

Der Manage-Server hält Release-Pakete und die Backups aller Instanzen – er ist
selbst sicherungswürdig. Zu sichern sind:

- `storage/` – Instanzen, Manifest, Pakete, Backups, Einstellungen
- `config.php` – Zugangsdaten

Bei aktivem S3-Archiv liegen die Backups zusätzlich im Bucket; `storage/instances.json`
und `storage/releases/` aber nicht.

## Betrieb

- Die Anmeldung ist pro IP begrenzt (Standard 10 Versuche je 15 Minuten).
- Ratenbegrenzung gilt auch für fehlgeschlagene API-Authentifizierungen.
- Protokolle liegen unter `storage/logs/` und rotieren automatisch.
- Ein Passwortwechsel erfolgt in `config.php`; angemeldete Sitzungen bleiben bis
  zum Ablauf bestehen. Sollen sie sofort enden, `session.save_path` leeren oder
  `session_name` in `includes/auth.php` ändern.

## Weiter

- [INSTANCE_MANAGEMENT](INSTANCE_MANAGEMENT.md) – Instanzen anlegen und Tokens vergeben
- [RELEASING](RELEASING.md) – Releases bauen und veröffentlichen
- [CONFIG_REFERENCE](CONFIG_REFERENCE.md) – alle Serverkonstanten