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

---

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/