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)

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.

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

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:

# 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.

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

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

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

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