---
title: "Configuration"
description: "Configuration file of the LumiScan Annotation Web server: address and port, HTTPS, project folders, database, backups, box suggestions, S3 and sign-in."
product: "LumiScan Annotation Web"
component: "lumiscan-annotation-web"
version: "2.1.0"
display_version: "2.1.0.0"
latest_version: false
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/configuration.html"
---

# Configuration – LumiScan Annotation Web

The server reads one JSON file, given with `--config`. An example with every section is in `config\annotation-server.example.json`. Relative paths are relative to the folder of the configuration file. Secrets (passwords, keys) can be kept in separate files that only the service account may read: use the keys ending in `_file`.

## Example

```json
{
  "bind": "0.0.0.0",
  "port": 8080,
  "public_url": "https://annotation.example.com",
  "projects_root": "../projects",
  "project_folders": ["D:/LumiScan"],
  "data_root": "D:/LumiScan/annotation-data",
  "database": "annotation-server.db",
  "web_root": "../www",
  "log_dir": "../logs",
  "backup": { "dir": "../backups", "every_hours": 24, "keep": 14 },
  "pre_annotation": [
    { "url": "http://gpu-server:8090", "token_file": "preannotate.token" }
  ],
  "auth": {
    "local_login": true,
    "default_role": "annotator",
    "ldap": { "enabled": false },
    "oidc": { "enabled": false }
  }
}
```

## Keys

| Key | Meaning |
| --- | --- |
| `bind`, `port` | Listen address (default `0.0.0.0`, all network interfaces) and port (default `8080`). |
| `public_url` | The address users open, for example `https://annotation.example.com`. Needed behind a reverse proxy and for single sign-on (redirect address). |
| `https` | `auto` (default), `on` or `off`. See [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/configuration.html#https). |
| `tls_cert`, `tls_key` | Certificate and private key (PEM) for HTTPS. Without them the server uses a self-signed certificate. See [HTTPS](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/configuration.html#https). |
| `tls_names` | Optional list: further host names or IP addresses for the self-signed certificate. |
| `web_root` | The web pages. Default: `www` next to the program. |
| `data_root` | Optional: an image folder that becomes the project `default`, open to all users. This is how existing installations of version 2.0 keep working. |
| `projects_root` | Folder for new and imported projects. Default: `projects` next to the configuration. |
| `project_folders` | Optional list: admins may create projects on existing folders only below these. |
| `s3_targets` | Optional list of S3 buckets for projects, see [Projects in S3 Buckets](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/projects-in-s3-buckets.html). |
| `pre_annotation` | Optional: one box suggestion service or a list of them, each with `url`, `token_file` (or `token`), `timeout_s`, `enabled`. See [Box Suggestion Service](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/box-suggestion-service.html). |
| `database` | The database: accounts, sessions, projects, history, notes. Default: `annotation-server.db` next to the configuration. **Local disk only**, never on a network share. |
| `index_refresh_seconds` | How often the project folders are scanned for changes made outside the web app. Default 60. |
| `lock_lease_seconds` | How long an edit lock lasts without renewal. Default 60; the browser renews it while the image is open. |
| `log_dir` | Folder for rotating log files. Without it, the log goes to the console only. |
| `backup.dir`, `backup.every_hours`, `backup.keep` | Automatic backups: folder (default `backups` next to the configuration), interval in hours (default 24), number kept (default 14). See [Backup and Restore](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/backup-and-restore.html). |
| `auth` | Sign-in methods and sessions, see [Sign-in Methods](https://docs.hdvisionsystems.com/en/lumiscan-annotation-web/2.1.0/sign-in-methods.html). |
| `license` | Prepared for the LumiScan Key; not used by this version. |

## HTTPS {#https}

The server speaks HTTPS by default, so passwords and session cookies never travel unencrypted. Users open `https://<server>:<port>/`, for example `https://annotation-pc:8080/`. The port speaks either HTTPS or HTTP: an address with `http://` gets no answer.

- **Self-signed certificate (default):** Without `tls_cert` and `tls_key`, the server creates a certificate at the first start and keeps it in the folder `tls` next to the configuration (`self-signed-cert.pem`, `self-signed-key.pem`). Nothing needs to be set up.
  - The certificate names the computer’s host name, `localhost`, the computer’s network addresses, the host of `public_url` and the entries of `tls_names`. Add to `tls_names` any further name or IP address users type, for example a DNS alias.
  - It is valid for 825 days. The server renews it 30 days before it expires, also while it runs, and when a name from `public_url` or `tls_names` is missing in it.
  - Browsers show a warning such as "Your connection is not private" until they trust the certificate. Compare the SHA-256 fingerprint in the warning’s certificate details with the one the server log shows at the start (`HTTPS: SHA-256 fingerprint …`), then continue. To avoid the warning, import `self-signed-cert.pem` on the clients as a trusted certificate (Windows: **Trusted Root Certification Authorities**, macOS: Keychain, **Always Trust**), or use a certificate of your company’s CA.
  - Back up the `tls` folder with the configuration (the automatic backups include it). A new certificate means a new warning on every client.

- **Your own certificate:** Set `tls_cert` and `tls_key` to the PEM files of a certificate from your company’s CA or a public CA (the certificate with its intermediate certificates) and its key. The server checks at the start that both belong together and warns 30 days before the certificate expires. Restart the server after replacing the files.
  ```json
    "tls_cert": "tls/annotation.pem",
    "tls_key": "tls/annotation.key",
  ```

- **Behind a reverse proxy (nginx, IIS, Apache):** The proxy terminates TLS and forwards to the server on the same computer, for example on `127.0.0.1:8080`. With `"bind": "127.0.0.1"` the server stays on plain HTTP by itself (`"https": "auto"`); otherwise set `"https": "off"`. Set `public_url` to the address users open. The proxy should send the header `X-Forwarded-Proto: https`, so the session cookie is marked secure.
  ```nginx
  server {
      listen 443 ssl;
      server_name annotation.example.com;
      ssl_certificate     /etc/ssl/annotation.pem;
      ssl_certificate_key /etc/ssl/annotation.key;
      client_max_body_size 64m;
      location / {
          proxy_pass http://127.0.0.1:8080;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-Proto https;
          proxy_read_timeout 600s;
      }
  }
  ```

  `client_max_body_size` must allow the 8 MB pieces of a project import.

## Sessions and security

- Sign-in creates a session cookie (HttpOnly, SameSite=Lax, Secure over HTTPS). A session ends after `auth.session_hours` without activity (default 12) and after `auth.max_session_days` at the latest (default 7).
- After 5 failed sign-ins an account is blocked for 15 minutes (30 failed attempts per network address).
- Disabling a user or resetting a password ends their sessions at once.
- Every change request needs the header `X-Requested-With: lsa`, which protects against cross-site requests.