diff --git a/README.md b/README.md index 9f0a088..3867291 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,121 @@ A .NET 8 messaging service for sending and receiving emails via SMTP, IMAP, POP3 --- +## Deployment als Windows-Dienst (empfohlen) + +Der Betrieb als **Windows-Dienst** ist dem IIS-Hosting ausdrücklich vorzuziehen, da: + +- Der RabbitMQ-Consumer dauerhaft läuft – unabhängig von eingehenden HTTP-Anfragen +- Kein IIS-Idle-Timeout, der den App-Pool beendet +- Automatischer Neustart bei Absturz (konfigurierbar) +- Verwaltung über die Windows-Dienstverwaltung (`services.msc`) oder PowerShell + +--- + +### Voraussetzungen + +- Windows Server (2016 oder neuer) +- .NET 8 Runtime **nicht erforderlich** – das Paket ist self-contained +- Administratorrechte auf dem Zielserver +- Port **1415** muss in der Firewall freigegeben sein + +--- + +### Schritt 1: Publish + +Auf dem Entwicklungsrechner im Repository-Verzeichnis: + +```powershell +.\publish-windows-service.ps1 +``` + +Die Ausgabe liegt anschließend unter: +``` +M:\App&Service\0 DD - Funktionsmodule\MessagingService\PreRelease\WindowsService\net8\ +``` + +--- + +### Schritt 2: Dateien auf den Server kopieren + +Den gesamten Publish-Ordner auf den Server kopieren, z. B. nach: +``` +D:\ProgramFiles\Digital Data\SERVICES\DigitalData.MessagingService\ +``` + +> **Wichtig:** Die Datei `appsettings.Secrets.json` wird **nicht** mit dem Publish-Paket ausgeliefert (sie ist nicht im Git-Repository). Diese Datei muss separat auf den Server kopiert werden. Sie enthält RabbitMQ-Zugangsdaten, E-Mail-Konten und weitere sensible Einstellungen. + +--- + +### Schritt 3: Dienst installieren + +Die Datei `install-windows-service.bat` liegt im Publish-Verzeichnis. Als Administrator ausführen: + +``` +install-windows-service.bat +``` + +Das Skript führt folgende Schritte automatisch aus: +1. Vorhandenen Dienst stoppen und löschen (falls vorhanden) +2. Neuen Windows-Dienst erstellen +3. Automatischen Neustart bei Absturz konfigurieren +4. Firewall-Regel für Port 1415 hinzufügen +5. Dienst starten + +--- + +### Schritt 4: Überprüfung + +Nach der Installation die API im Browser aufrufen: +``` +http://SERVER-IP:1415/swagger +http://SERVER-IP:1415/health +http://SERVER-IP:1415/serilog-ui +``` + +Dienststatus prüfen: +```powershell +sc.exe query "DD-MessagingService" +# oder +Get-Service "DD-MessagingService" +``` + +--- + +### Update (neue Version einspielen) + +```powershell +# 1. Dienst stoppen +sc.exe stop "DD-MessagingService" + +# 2. Neue Dateien ins Verzeichnis kopieren (appsettings.Secrets.json NICHT überschreiben) + +# 3. Dienst starten +sc.exe start "DD-MessagingService" +``` + +--- + +### Dienst entfernen + +```powershell +sc.exe stop "DD-MessagingService" +sc.exe delete "DD-MessagingService" +``` + +--- + +### Konfiguration + +| Einstellung | Datei | Beschreibung | +|---|---|---| +| `Hosting:UseWindowsService` | `appsettings.json` | `true` = Windows-Dienst-Modus aktiv | +| `Hosting:Urls` | `appsettings.json` | Bind-Adresse und Port, z. B. `http://0.0.0.0:1415` | +| `DataProtection:PersistKeysToFileSystem` | `appsettings.json` | `true` = Schlüssel werden im Verzeichnis `dp-keys/` gespeichert, unabhängig vom Windows-Benutzer | + +--- + + ## Email Account Configuration Each account is configured under `EmailAccounts.Accounts` in `appsettings.Secrets.json`. @@ -39,7 +154,7 @@ Each account is configured under `EmailAccounts.Accounts` in `appsettings.Secret | Value | Meaning | |-------|---------| -| `0` | None — send-only account, skipped by sync worker | +| `0` | None � send-only account, skipped by sync worker | | `1` | IMAP with username/password | | `2` | POP3 with username/password | | `3` | IMAP with OAuth2 | @@ -92,7 +207,7 @@ automatically for all subsequent operations. #### Obtaining the refresh token via the built-in authorization endpoint -The application provides a built-in OAuth2 flow — no external tools needed. +The application provides a built-in OAuth2 flow � no external tools needed. 1. Open a browser and navigate to: ``` @@ -101,7 +216,7 @@ The application provides a built-in OAuth2 flow Example: `https://localhost:7261/api/oauth2/google/authorize/3` 2. You will be redirected to Google's consent screen. If you see **"Google hasn't verified this app"**, - click **Continue** — this is expected while the app is in Testing mode. + click **Continue** � this is expected while the app is in Testing mode. 3. Sign in with the Gmail account and grant access. @@ -122,7 +237,7 @@ The application provides a built-in OAuth2 flow ### Microsoft 365 / Exchange Online (Azure AD) -Microsoft uses **application-level OAuth2** (client credentials flow — no user interaction required). +Microsoft uses **application-level OAuth2** (client credentials flow � no user interaction required). Tokens are acquired automatically using the client ID, secret and tenant ID. No authorization endpoint needs to be visited. @@ -154,12 +269,12 @@ needs to be visited. 5. Set `OAuth2TenantId` to the full domain (e.g. `yourorg.onmicrosoft.com`) or tenant GUID. > ?? `OAuth2ClientSecret` must be the **Value** shown at secret creation time, not the Secret ID (GUID). -> The value is only visible once — if lost, create a new secret. +> The value is only visible once � if lost, create a new secret. > ?? `OAuth2TenantId` must be a full domain (`yourorg.onmicrosoft.com`), a tenant GUID, > or `common`. Short names like `yourorg` are not valid and will cause `AADSTS900023`. -> No browser-based authorization is required for Microsoft — the application acquires tokens +> No browser-based authorization is required for Microsoft � the application acquires tokens > automatically on first use and caches them in memory until 5 minutes before expiry. @@ -200,7 +315,7 @@ Each account is configured under `EmailAccounts.Accounts` in `appsettings.Secret | Value | Meaning | |-------|---------| -| `0` | None — send-only account, skipped by sync worker | +| `0` | None � send-only account, skipped by sync worker | | `1` | IMAP with username/password | | `2` | POP3 with username/password | | `3` | IMAP with OAuth2 | @@ -235,7 +350,7 @@ Google uses **user-delegated OAuth2** (not client credentials). A one-time autho } ``` -#### Setup — obtaining the refresh token (one-time) +#### Setup � obtaining the refresh token (one-time) 1. Go to [console.cloud.google.com](https://console.cloud.google.com) and create or select a project. 2. Enable the **Gmail API** under *APIs & Services ? Library*. @@ -264,7 +379,7 @@ Google uses **user-delegated OAuth2** (not client credentials). A one-time autho ### Microsoft 365 / Exchange Online (Azure AD) -Microsoft uses **application-level OAuth2** (client credentials flow — no user interaction required). +Microsoft uses **application-level OAuth2** (client credentials flow � no user interaction required). #### Required fields @@ -294,7 +409,7 @@ Microsoft uses **application-level OAuth2** (client credentials flow 5. Set `OAuth2TenantId` to the full domain (e.g. `yourorg.onmicrosoft.com`) or tenant GUID. > ?? `OAuth2ClientSecret` must be the **Value** shown at secret creation time, not the Secret ID (GUID). -> The value is only visible once — if lost, create a new secret. +> The value is only visible once � if lost, create a new secret. > ?? `OAuth2TenantId` must be a full domain (`yourorg.onmicrosoft.com`), a tenant GUID, > or `common`. Short names like `yourorg` are not valid and will cause `AADSTS900023`.