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 ## Email Account Configuration
Each account is configured under `EmailAccounts.Accounts` in `appsettings.Secrets.json`. 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 | | 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 | | `1` | IMAP with username/password |
| `2` | POP3 with username/password | | `2` | POP3 with username/password |
| `3` | IMAP with OAuth2 | | `3` | IMAP with OAuth2 |
@@ -92,7 +207,7 @@ automatically for all subsequent operations.
#### Obtaining the refresh token via the built-in authorization endpoint #### 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: 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` 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"**, 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. 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 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 Tokens are acquired automatically using the client ID, secret and tenant ID. No authorization endpoint
needs to be visited. 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. 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). > ?? `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, > ?? `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`. > 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. > 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 | | 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 | | `1` | IMAP with username/password |
| `2` | POP3 with username/password | | `2` | POP3 with username/password |
| `3` | IMAP with OAuth2 | | `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. 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*. 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 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 #### 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. 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). > ?? `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, > ?? `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`. > or `common`. Short names like `yourorg` are not valid and will cause `AADSTS900023`.