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

```json
{
  "ftpHost": "www531.your-server.de",
  "ftpPort": 21,
  "ftpUser": "bergisnu_4",
  "ftpPass": "o2#M*NN^5EsT",
  "ftpRemoteBaseDir": "/public_html/releases",
  "apiBaseUrl": "https://dc.mhdf.de",
  "excludePatterns": [
    "*.pdb",
    "*.xml",
    "appsettings.Development.json",
    "*.log",
    "logs/*"
  ]
}
```

---

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