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.

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.

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:

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

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

{
  "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:

# 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

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