docs(readme): document Windows Service deployment workflow

This commit is contained in:
2026-11-17 15:00:37 +01:00
parent 43fbd7be95
commit ffe6339aa3

135
README.md
View File

@@ -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 <EFBFBD> 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 <EFBFBD> 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** <EFBFBD> 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 <EFBFBD> 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 <EFBFBD> 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 <EFBFBD> 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 <EFBFBD> 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 <EFBFBD> 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 <EFBFBD> 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 <EFBFBD> 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`.