﻿# Configuration (appsettings.json)

> Settings needed at start-up live in appsettings.json in the application folder (in Docker: mounted to /app/appsettings.json). The file is commented. Settings that administrators change at run time are in App Konfiguráció instead (App configuration).

Source: https://workwise-solutions.net/docs/installation/configuration/ · Language: en · Hungarian version: https://workwise-solutions.net/hu/docs/installation/configuration/

Settings needed at start-up live in `appsettings.json` in the application folder (in Docker: mounted to `/app/appsettings.json`). The file is commented. Settings that administrators change at run time are in **App Konfiguráció** instead ([App configuration](https://workwise-solutions.net/docs/features/app-configuration/)).

- **Environment variables override the file.** Use `__` between sections and `__0`, `__1` for array items, for example `ConnectionStrings__InternalDb`, `HttpSettings__Urls__0`, `Serilog__MinimumLevel__Default`.
- **Timespans** are written as `d.hh:mm:ss`, for example `60.00:00:00` for 60 days.
- At every start the application adds settings that a new release introduced, with their defaults, after saving a backup copy (`appsettings.json.backup.<timestamp>`). Existing values are kept. A read-only file is left alone; the new settings then use their defaults in memory.
- Restart the application after changing the file. Use the same values on every server.

![Where settings come from](https://workwise-solutions.net/docs/images/diagram-configuration-sources-en.png)
*Environment variables override appsettings.json at start; App Konfiguráció settings live in the database and reach every server at run time.*

## Internal database

```jsonc
"ConnectionStrings": {
  "InternalDbType": 0,          // 0 SQLite | 1 SQL Server | 2 PostgreSQL | 3 MySQL
  "InternalDb": "Data Source=database.db;",
  "Schema": "",                 // must stay empty for SQLite and MySQL
  "MySqlServerVersion": "8.0.28" // MySQL only
}
```

Example connection strings:

| Type | Connection string |
|---|---|
| SQLite (0) | `Data Source=database.db;` |
| SQL Server (1) | `Data Source=host;Initial Catalog=database;User id=user;Password=...;Connection Timeout=60;Encrypt=false;` |
| PostgreSQL (2) | `Server=host;Port=5432;Database=worksmarthub;User id=user;Password=...;` |
| MySQL (3) | `Server=host;Port=3306;Database=worksmarthub;Uid=user;Pwd=...;` |

The database is created and migrated at start-up. A file that uses the newer `InternalDatabaseSettings` section takes precedence over `ConnectionStrings` and its environment variables.

## Cache

`CacheSettings.Type`: `InMemory` (default, single server only), `Redis` (recommended for several servers, with `RedisCacheSettings.Configuration`), `SqlServer`, `Postgres` or `MySql` (a table in that database), or `None` (not supported with OAuth).

## Public address (PublicBaseUrl)

The address users open the application at, including any path prefix, for example `https://wsh.example.com/`. Links that leave the current request are built from it: links in e-mails (password reset, unsubscribe, the application link in notifications, also from background jobs), the links stored for later e-mails, and the address in the mobile activation QR code. When empty, these links are built from each request's address, which a sender can manipulate; the application logs a `SECURITY:` warning at every start. Set it on every installation that others can reach.

## Listen address

`HttpSettings.Urls` (default `http://localhost:5000`). Behind a reverse proxy on the same machine keep the default. To accept external connections use `http://+:5000` (one entry per port). In Docker set `HttpSettings__Urls__0=http://+:8080`. Under IIS it is not used. This section can only come from the JSON file, the command line or environment variables. `HttpSettings.Cors` controls cross-origin access (only needed when another web origin calls the API from a browser).

## Signing keys

Three keys sign tokens and links. The shipped file contains public default values; **replace each with a different long random value before first use** (for example `openssl rand -base64 48`), identical on every server:

| Setting | Signs |
|---|---|
| `LoginSettings.JwtAuthenticationSettings.SymmetricSecurityKey` | Sign-in tokens and personal access tokens. With the default, anyone could forge a token. Changing it ends every session and token. |
| `TicketAttachment.DownloadLink.SymmetricSecurityKey` | Attachment download links |
| `ImageConfiguration.ImageLink.SymmetricSecurityKey` | Component image links |

Changing the two link keys later invalidates the links of all files uploaded before. While a key has its shipped value, the application logs a `SECURITY:` warning at start.

## Sign-in

`UserSettings.UserStore` and `LoginSettings.AuthType` select where users come from and how they sign in; see [Authentication options](https://workwise-solutions.net/docs/installation/authentication/). Other login settings:

| Setting | Default | Meaning |
|---|---|---|
| `LoginSettings.SessionDuration` | `60.00:00:00` | Session length, extended on use |
| `LoginSettings.PasswordResetLinkDuration` | `30.00:00:00` | Validity of password reset links |
| `LoginSettings.CookieAuthenticationSettings.SecureCookie` | `true` | Must stay `true` on deployed installations (HTTPS) |

## E-mail (SMTP)

`EmailSettings` is used for e-mails that do not go through notification channels: client e-mails, password reset, new-user details, inactivity reminders, low-stock and service user warnings.

```jsonc
"EmailSettings": {
  "SmtpHost": "smtp.example.com",
  "SmtpPort": 587,
  "SslEnabled": true,
  "SmtpUser": "...",
  "SmtpPassword": "...",
  "Timeout": 20,
  "FromEmail": "noreply@example.com",
  "FromName": "WorkSmartHub"
}
```

## Uploads and images

| Setting | Default | Meaning |
|---|---|---|
| `TicketAttachment.UploadChunkSize` | `25mb` | Chunk size of attachment uploads. A reverse proxy must accept bodies at least this large. |
| `TicketAttachment.DownloadLink.TokenExpiration` | 3650 days | Lifetime of attachment links |
| `ImageConfiguration.ImageChunkSize` | `25mb` | Chunk size of image uploads |
| `ImageConfiguration.MaxWidthHeight_Large/Medium/Small` | 512 / 256 / 128 | Sizes of stored component images |
| `ImageConfiguration.MaxPixels` | 40000000 | Largest accepted image |

## Logging

`Serilog.WriteTo` defines the console and the file sink (`Logs/log-.txt`, one file per day). Keep the file sink: the **Naplófájlok** page reads it. Minimum levels: `Serilog:MinimumLevel:Default` and the overrides for `Microsoft` and `System` (Information when not set), or the override in **App Konfiguráció → Log Szintek**.

## Other settings

| Setting | Meaning |
|---|---|
| `Swagger.Enabled` | Turns the Swagger UI at `/swagger` on (default) or off ([API usage](https://workwise-solutions.net/docs/api-usage/)) |
| `UseDetailedExceptions` | Include details of unhandled errors in API answers |
| `ConfigSync.Enabled`, `ConfigSync.IntervalSettings.Interval` | How often servers pick up App configuration changes (10 s) |
| `Notifications.Teams.ServiceUrl` | The Microsoft Teams service endpoint |

## Protect the file

`appsettings.json` contains the signing keys and connection passwords. Make it readable only by administrators and the application's account. Backups of it, and of the database, contain secrets ([Upgrading, backup and restore](https://workwise-solutions.net/docs/installation/upgrade-backup-restore/)).
