Configuration

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

{
  "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.

tls_cert, tls_key

Certificate and private key (PEM) for HTTPS. Without them the server uses a self-signed certificate. See 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.

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.

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.

auth

Sign-in methods and sessions, see Sign-in Methods.

license

Prepared for the LumiScan Key; not used by this version.

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.

  "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.

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.