Configuration: where the settings live

All values sit under the InvoiceApi section. Three sources, from the inside out:

Source	When
appsettings.Production.json in the target directory	the normal case. The installer creates the file and leaves it untouched on every update
Environment variables InvoiceApi__…	for secrets and machine-specific values
appsettings.json	no — see the warning

With environment variables, each configuration level is separated by a double underscore: InvoiceApi__Smtp__Host, InvoiceApi__Deployment__Mode; lists carry an index: InvoiceApi__KnownProxies__0.

Host overrides do not belong in appsettings.json

That file is part of the program files and is overwritten by every update — your change would be gone after the next one. What counts is appsettings.Production.json, which updates leave alone, or the environment.

Two secrets are read directly from the environment as well, taking precedence over the configuration file: GDPICTURE_LICENSE_KEY and OCR_RESOURCE_FOLDER.

Restart the service after every change

The only exception is the API keys: the service picks up changes to keys/api-keys.json within 15 seconds without a restart.

The service aborts on nonsense

The values are checked at startup. The upload limit, result lifetime, rate-limit values, batch size, magic-link lifetime and session duration must be positive.

Why a failure to start beats faulty operation

Running quietly with unusable limits — an upload limit of 0, a negative session duration — would be harder to find than a service that never comes up and writes the reason to the log.

A complete example

{
  "InvoiceApi": {
    "Deployment": { "Mode": "OnPremise" },        // do not change
    "DataDirectory": "D:\\Invoiceflair\\Daten",
    "PublicBaseUrl": "https://rechnung.firma.de",
    "KnownProxies": [ "10.0.0.5" ],               // the reverse proxy's address
    "Smtp": {
      "Host": "smtp.firma.de", "Port": 587,
      "User": "…", "Password": "…",
      "From": "rechnung@firma.de", "UseStartTls": true
    },
    "GdPictureLicenseKey": "",                    // optional, only OCR + Word templates
    "OcrResourceFolder": "ocr-resources"          // optional
  },
  "Kestrel": {
    "Endpoints": {
      "Http":  { "Url": "http://0.0.0.0:5060" },
      "Https": { "Url": "https://0.0.0.0:5061",
                 "Certificate": { "Path": "C:\\certs\\firma.pfx", "Password": "…" } }
    }
  }
}

The options in detail

The complete tables — default, effect and the name of the environment variable per option — sit in the reference:

Area	Page
Uploads, volumes, rate limiting	Options: uploads and limits
Usage log and retention	Options: logging and retention
PDF import, OCR, licence	Options: PDF import and OCR
Mail, contact addresses, CORS, proxies	Options: mail and network
Switching capabilities on and off	Feature flags