Installing the Server

Windows 11

  1. Unpack LumiScanAnnotationWeb-<version>-win64.zip, for example to C:\LumiScanAnnotationWeb. It contains:

    C:\LumiScanAnnotationWeb\
    lumiscan-annotation-server.exe    the server
    www\                              the web pages
    config\annotation-server.example.json
    README.md, Changelog.md

  2. Copy config\annotation-server.example.json to config\annotation-server.json and adapt it, see Configuration. To start, set at least port and either data_root (an existing image folder) or projects_root.

  3. Start the server in a command prompt:

    cd C:\LumiScanAnnotationWeb
lumiscan-annotation-server.exe --config config\annotation-server.json

  4. Allow the port (default 8080) in the Windows firewall for the network the users are in.

Ubuntu 24.04

  1. Copy the server and the www folder, for example to /opt/lumiscan-annotation-web, and the configuration to /etc/lumiscan-annotation-web/annotation-server.json.

  2. Create a service account that may read and write the project folders:

    sudo useradd --system --home-dir /var/lib/lumiscan-annotation-web --create-home --shell /usr/sbin/nologin lsa
sudo chown -R lsa: /etc/lumiscan-annotation-web

  3. Start it once by hand to check the configuration:

    sudo -u lsa /opt/lumiscan-annotation-web/lumiscan-annotation-server --config /etc/lumiscan-annotation-web/annotation-server.json

First sign-in

At the first start, with no accounts yet, the server creates the local user admin with a random password and writes it to initial-admin-password.txt next to the database (the log names the file).

  1. Open https://<server>:8080/ in the browser. The browser warns about the self-signed certificate: compare the fingerprint with the server log and continue, see HTTPS.

  2. Sign in as admin with that password.

  3. Choose a new password. The file is then deleted.

  4. Create the other accounts, or set up the directory or single sign-on, see Users and Roles.

If nobody can sign in as administrator any more:

lumiscan-annotation-server --config <configuration> --reset-password admin

This prints a new password (and creates the account if it is missing). It must be changed at the next sign-in.

Starting the server automatically

The server is one program without a window. Start it at boot with the usual tools of the operating system, as the service account.

Linux (systemd), /etc/systemd/system/lumiscan-annotation-web.service
[Unit]
Description=LumiScan Annotation Web
After=network-online.target
Wants=network-online.target

[Service]
User=lsa
ExecStart=/opt/lumiscan-annotation-web/lumiscan-annotation-server --config /etc/lumiscan-annotation-web/annotation-server.json
Restart=on-failure

[Install]
WantedBy=multi-user.target

Then sudo systemctl enable --now lumiscan-annotation-web.

Windows (Task Scheduler), in an administrator PowerShell
$exe = "C:\LumiScanAnnotationWeb\lumiscan-annotation-server.exe"
$action = New-ScheduledTaskAction -Execute $exe -Argument "--config C:\LumiScanAnnotationWeb\config\annotation-server.json" -WorkingDirectory "C:\LumiScanAnnotationWeb"
$trigger = New-ScheduledTaskTrigger -AtStartup
$settings = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit ([TimeSpan]::Zero)
Register-ScheduledTask -TaskName "LumiScan Annotation Web" -Action $action -Trigger $trigger -Settings $settings -User "SYSTEM" -RunLevel Highest

The account must be able to read and write the project folders; for network shares, use a domain service account instead of SYSTEM.

Command-line options

Options on the command line override the configuration file.

--config <file>

the configuration file (JSON)

--data-root <dir>

a folder with images, becomes the project default

--bind <address>, --port <port>

listen address (default 0.0.0.0) and port (default 8080)

--https <mode>

auto, on or off, see HTTPS

--web-root <dir>

the web pages (default: www next to the program)

--log-dir <dir>

write rotating log files there

--database <file>

the database (default: annotation-server.db next to the configuration); local disk only

--backup <file>

write a backup and exit; works while the server runs

--restore <file>

restore a backup and exit; the server must be stopped (--force skips that check)

--reset-password <user>

give a local user a new random password, print it and exit

--version, --help

version, list of options

Updating

  1. Stop the server. Optional, but recommended: make a backup first (--backup, see Backup and Restore).

  2. Replace the program and the www folder. Keep the configuration and the database.

  3. Start the server. It updates its database itself if needed.

  4. Users reload the page in the browser.