Deploymentcenter/docs/UPDATESERVICE_INTEGRATION_GUIDE.md

# Deploymentcenter — UpdateService Integration & Deployment Guide

> **⚠️ Geändert in Version 2.0** — Das Veröffentlichen eines Releases läuft jetzt
> über `POST /api/updateservice/v1/publish` und verlangt ein Token mit dem Scope
> `updateservice:publish` (zuvor völlig ungeschützt). Der Versionsvergleich folgt
> jetzt der semantischen Versionsordnung, `1.10.0` gilt also korrekt als neuer
> als `1.9.0`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.


Das **UpdateService-Modul** des Deploymentcenters bietet ein unternehmensweites, leichtgewichtiges Update-, Rollback- und Reparatur-Schema auf Basis eines LEMP-Stacks (Nginx Static Files + PHP API).

---

## 1. Übersicht & Architektur

- **Kein dauerhafter Background-Dienst**: Hauptanwendungen prüfen beim Start einmalig schnell und netzwerktolerant auf verfügbare Updates und Dateiintegrität.
- **Entkoppelte Ausführung**: Bei Handlungsbedarf beendet sich die Hauptanwendung sauber und übergibt die Kontrolle an den eigenständigen Console Agent (`update-agent.exe` / `update-agent`).
- **3-Kanal-System**: Kanäle `prod` (Produktiv), `beta` (Vorab-Test), `dev` (Entwicklung).
- **Statische LEMP-Verteilung**: Downloads und Versionen-Manifeste (`latest.json`, `manifest.json`, `package.tar.gz`) werden über Nginx extrem performant bereitgestellt.

---

## 2. Integration in .NET Client-Anwendungen

### A. Referenz auf `Deploymentcenter.Client`

Binde das Projekt oder Paket `Deploymentcenter.Client` in deine Anwendung ein.

```csharp
using Deploymentcenter.Client;
using Deploymentcenter.Client.Models;

// Early Start Hook in Program.cs (oder App.xaml.cs)
var updateClient = new UpdateClient();
var checkResult = await updateClient.CheckForUpdateAsync(
    baseUrl: "https://dc.mhdf.de",
    projectId: "myapp",
    currentVersion: BuildInfo.Version,
    channel: "prod"
);

if (checkResult.UpdateAvailable)
{
    Console.WriteLine($"[UPDATE] Neues Release v{checkResult.LatestRelease.Version} verfügbar!");

    // UpdateAgent starten und Hauptanwendung beenden
    UpdateClient.LaunchUpdateAgent(
        agentPath: "update-agent.exe",
        projectId: "myapp",
        channel: "prod",
        action: "update",
        version: "latest",
        exitCurrentApp: true
    );
}
```

### B. MSBuild BuildInfo Generierung

Binde das `Deploymentcenter.BuildInfo.targets` Script in deine `.csproj` ein, damit Version, UTC-Build-Datum und Git Commit-Hash automatisch zur Übersetzungszeit generiert werden:

```xml
<Import Project="..\Deploymentcenter.Client\Deploymentcenter.BuildInfo.targets" />
```

---

## 3. Packaging & Deployment CLI (`pack-and-deploy`)

Das Packaging-Tool verpackt den `dotnet publish`-Output, berechnet Hashes, erzeugt das `manifest.json` und lädt alles per FTP auf den LEMP-Server.

### Aufruf-Beispiel:

```bash
# Automatisierter Release-Publish via CLI
pack-and-deploy --project myapp --version 1.4.0 --channel prod --publish-dir ./bin/Release/net8.0/publish --changelog "Fehlerbehebungen und Performance-Optimierung"
```

### Konfiguration (`packager.config.json`)

> Diese Datei enthält Zugangsdaten und ist per `.gitignore` von der
> Versionskontrolle ausgeschlossen. Vorlage: `packager.config.example.json`.
> In der vorherigen Fassung standen die echten FTP-Zugangsdaten sowohl hier in
> der Anleitung als auch als Standardwerte im Quelltext von `Program.cs`.

```json
{
  "ftpHost": "ftp.example.com",
  "ftpPort": 21,
  "ftpUser": "ftp-user",
  "ftpPass": "ftp-password",
  "ftpRemoteBaseDir": "/public_html/releases",
  "apiBaseUrl": "https://dc.mhdf.de",
  "apiToken": "dc_sub_...",
  "excludePatterns": [
    "*.pdb",
    "*.xml",
    "appsettings.Development.json",
    "*.log",
    "logs/**"
  ]
}
```

`apiToken` braucht das Recht `updateservice:publish`. Ohne Token baut und lädt
der Packager das Paket zwar hoch, meldet es aber nicht beim Deploymentcenter an
und beendet sich mit Rückgabewert 2.

### Alternative: Umgebungsvariablen

Für CI-Läufe, in denen keine Datei abgelegt werden soll — sie haben Vorrang vor
der Konfigurationsdatei:

```bash
export DC_FTP_HOST=ftp.example.com
export DC_FTP_USER=ftp-user
export DC_FTP_PASS='...'
export DC_TOKEN='dc_sub_...'

pack-and-deploy --project myapp --version 1.4.0 --channel prod \
                --publish-dir ./bin/Release/net8.0/publish
```

### Rückgabewerte

| Wert | Bedeutung |
|---|---|
| `0` | Paket gebaut, hochgeladen und im Deploymentcenter registriert |
| `1` | Konfiguration unvollständig oder Publish-Verzeichnis fehlt — nichts wurde ausgeführt |
| `2` | Teilweise fehlgeschlagen: FTP-Upload oder Registrierung ging schief |

Zuvor lieferte das Werkzeug in allen Fällen `0` und meldete „successfully
published", selbst wenn FTP-Upload und API-Aufruf beide fehlgeschlagen waren.

---

## 4. Standalone UpdateAgent (`update-agent`)

Der `update-agent` kann sowohl interaktiv (Spectre.Console Terminal UI) als auch im Headless CLI-Modus betrieben werden.

### CLI Modus Befehle:

```bash
# Nach Updates suchen
update-agent --project myapp --channel prod --action check

# Auf neueste Version aktualisieren
update-agent --project myapp --channel prod --action update --version latest --target-dir /opt/myapp

# Rollback auf ältere Version
update-agent --project myapp --channel prod --action update --version 1.3.2

# Integritäts-Reparatur der aktuellen Installation
update-agent --project myapp --channel prod --action repair

# Alle verfügbaren Versionen auflisten
update-agent --project myapp --channel prod --action list
```

---

## 5. LEMP Verzeichnisstruktur auf dem Server

```text
/var/www/releases/ (oder /public_html/releases/)
└── {ProjectId}/                    # z.B. myapp, polytrader
    ├── prod/
    │   ├── latest.json             # Kanal-Übersicht & neueste Version
    │   ├── 1.4.0/
    │   │   ├── package.tar.gz      # Das gezippte Release
    │   │   ├── package.tar.gz.sha256
    │   │   └── manifest.json       # Einzeldateien + Hashes
    │   └── 1.3.9/
    ├── beta/
    └── dev/
```