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
```

---

## 4a. Prüf-Endpunkte (für eigene Anbindungen)

Die Lese-Endpunkte sind bewusst **ohne Token** erreichbar, damit ausgelieferte
Anwendungen ohne Anpassung weiter nach Updates suchen können. Sie liefern nur
Release-Metadaten, die über die Download-URL ohnehin öffentlich sind.

```bash
GET /api/updateservice/v1/check?product=myapp&version=1.4.2&channel=prod
```

```json
{
  "status": "success",
  "update_available": true,
  "current_version": "1.4.2",
  "latest_version": "1.4.3",
  "is_critical": false,
  "latest_release": {
    "version": "1.4.3",
    "download_url": "https://dc.mhdf.de/releases/myapp/prod/1.4.3/package.tar.gz",
    "sha256_hash": "e3b0c442...",
    "git_commit": "a21536f",
    "size_bytes": 8412160,
    "release_notes": "Behebt den Login-Fehler.",
    "is_critical": 0
  }
}
```

Weitere Endpunkte:

| Aufruf | Zweck |
|---|---|
| `GET .../latest?product=myapp&channel=prod` | Höchstes Release, unabhängig von der Client-Version |
| `GET .../releases?product=myapp` | Alle Releases, nach Versionsordnung sortiert |

### Versionsvergleich

Der Vergleich folgt der semantischen Versionsordnung. Konkret bedeutet das:

| Installiert | Verfügbar | Update? |
|---|---|---|
| `1.9.0` | `1.10.0` | ja — zweistellige Minor ist höher |
| `1.10.0` | `1.9.0` | nein |
| `1.0.0-rc.1` | `1.0.0` | ja — Release schlägt Vorabversion |
| `1.0.0` | `1.0.0-rc.1` | nein |
| `v1.4.2` | `v1.4.3` | ja — führendes `v` wird ignoriert |

> Zuvor verglich der Server lexikografisch. `1.9.0` galt dadurch als neuer als
> `1.10.0`, und Clients bekamen ein Downgrade als Update angeboten. Derselbe
> Fehler steckte im .NET-Client bei `v`-präfigierten Versionen und ist dort
> ebenfalls behoben.

### Verknüpfung mit dem Bugtracker

Beim Veröffentlichen schließen sich alle Bugtracker-Items, deren
`resolved_in_build` der veröffentlichten Version entspricht, automatisch. Die
Antwort nennt die Anzahl:

```json
{ "status": "success", "release_id": 12, "created": true, "auto_resolved": 3,
  "message": "Release 1.4.3 (prod) für \"myapp\" veröffentlicht. 3 Bugtracker-Item(s) automatisch geschlossen." }
```

Damit schließt sich der Kreis: Ein Agent markiert einen Bug als „gelöst in
v1.4.3", der Packager veröffentlicht v1.4.3, und das Item schließt sich selbst.

---

## 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/
```