docs(readme): document Windows Service deployment workflow
This commit is contained in:
135
README.md
135
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
|
## 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`.
|
||||||
|
|||||||
Reference in New Issue
Block a user