Download Data Orchester

DataOrchester installs on Linux from the install package: one archive holding the DataOrchester jar, its configuration file application.properties and the install scripts. install.sh verifies the package, installs a private Java runtime, registers DataOrchester as a systemd service under an unprivileged account, creates the first administrator and starts it. It runs on any Linux with systemd and glibc, on x64 or arm64; releases are tested on Ubuntu 24.04, Debian 12 and Rocky Linux 9. Without systemd, use the container image.

The install script

To change a setting before installing - the port (8080 by default), the title, the language, the time zone - edit application.properties in the extracted directory first. Every key is in the configuration reference.

The script needs openssl, and curl or wget. Before it changes anything, it checks the jar and the Java runtime against the package's signed checksums.txt, with the release key pinned inside it, and stops with Nothing was changed if either does not match. Then it:

1. downloads Temurin 25, a Java runtime, from Adoptium, and verifies it the same way;
2. creates the service account, the program directory and the instance home, and copies application.properties into the home;
3. asks for the first administrator's password, at least 12 characters, twice;
4. writes the systemd unit, starts it and waits until it answers;
5. prints the address to open and, when ufw or firewalld is active, the command that opens the port - it never changes the firewall itself.

Options

Option	Effect
--config FILE	Use this configuration file instead of the package's application.properties; on an upgrade, replace the home's copy with it
--admin ACCOUNT	The first local administrator, instead of install.admin-account (ADMIN)
--admin-password-file FILE	Read that administrator's password from the file's first line
--admin-no-password	Create the administrator without a password: whoever reaches the sign-in page first defines it. Only when you ask for it
--activation-code CODE	A licence activation code - letters, digits and dashes - redeemed at the first start; see Licence activation
--java PATH	Run on this Java 25 instead of a private runtime
--runtime FILE	The Temurin archive for this machine, for an install with no network; it is verified all the same
--unattended	Ask nothing: generate the password unless one is given
--uninstall [--purge]	Remove DataOrchester, and with --purge its data too; see Uninstalling

sh install.sh --help lists them as well. An unattended install that activates a licence:

sudo sh install.sh --unattended --activation-code ABCD-1234

The script's exit code, for automation:

Code	Meaning
0	Done
1	Refused; the message says why
2	A usage error in the options
3	Nothing to install for the administrator you asked for: one already exists

What it sets up

What	Where
Program: the jar and the Java runtime	/opt/data-orchester
Instance home: application.properties, entities/, logs/, loggers/, instance/, tmp/, theme/	/var/lib/data-orchester, owned by the service account; instance/ is readable by it alone
Service	systemd unit data-orchester, enabled at boot and restarted whenever it exits. It writes only to the instance home, with a private /tmp and no way to gain privileges, and may listen on a port below 1024
Account	data-orchester, a system account that cannot sign in, in the dialout group for the serial ports
Activation code	/etc/data-orchester/data-orchester.env, mode 0600, which systemd reads as root

Nothing Java-related on the machine changes: the runtime is DataOrchester's own. What each directory of the home holds is in the configuration reference.

First sign-in

Open the address the script printed.

• You typed a password: sign in as ADMIN with it.
• The script generated one - with no terminal, or with --unattended: it printed it once, and kept it in /opt/data-orchester/admin-password.txt, which only root can read. Sign in with it: the sign-in card then asks for a new password, which must differ from the generated one, before anything else is granted. The file is worthless from then on, and can be deleted.

The script hands the password to the jar's identity-setup in ORCHESTER_ADMIN_PASSWORD, never on a command line other processes could read. To install a directory or single sign-on provider instead of a local administrator, name its record in install.identity-provider before installing; see Sign-in and identity providers. Then carry on with After installing.

Running it

sudo systemctl status data-orchester
sudo systemctl restart data-orchester
sudo journalctl -u data-orchester -f
sudo tail -f /var/lib/data-orchester/logs/server.log

The instance reads /var/lib/data-orchester/application.properties at every start, not the package's copy: edit it with sudo, then sudo systemctl restart data-orchester.

Behind a reverse proxy

When a proxy terminates TLS in front of DataOrchester, list it in the home's application.properties, or every operator appears to come from the proxy:

application.trusted-proxies=10.0.0.5
application.public-base-url=https://orchester.example.cl

application.trusted-proxies takes IPv4 and IPv6 addresses, and IPv4 CIDR blocks, separated by commas. Loopback is always trusted, so a proxy on the same machine needs no entry: set server.address=127.0.0.1 instead, and only that proxy can reach DataOrchester. SITE_TRUSTED_PROXIES, in the service's environment, overrides the key:

sudo systemctl edit data-orchester

[Service]
Environment=SITE_TRUSTED_PROXIES=10.0.0.5

Troubleshooting

Symptom	What to do
A checksum or signature message, then Nothing was changed	The package or the runtime is not what the release signed. Download it again, and verify it before extracting
this Linux does not run systemd	Use the container image
openssl is needed to verify the package	Install openssl with the distribution's package manager, and run the script again
could not download the runtime	No route to github.com. On a connected machine, download the Temurin JRE archive of the version the download page names - OpenJDK25U-jre_x64_linux_hotspot_25.0.4.1_1.tar.gz for 25.0.4.1+1 on x64, aarch64 in place of x64 on arm64, from Adoptium's temurin25-binaries releases on GitHub - and pass it with --runtime
DataOrchester did not answer within 180 seconds	sudo journalctl -u data-orchester, and logs/server.log in the home
Other machines cannot reach it	Open the port in the host firewall - the script printed the ufw or firewall-cmd command if one is active - and in any firewall between
Support asks for a self-check	/opt/data-orchester/runtime/bin/java -jar /opt/data-orchester/data-orchester.jar selfcheck proves the jar's libraries load on this machine

Without the script

Where install.sh does not apply and the container image does not suit, run the jar by hand. It needs a Java 25, a home directory it owns, and a dedicated account; it serves from its working directory, which is its instance home.

sudo mkdir -p /opt/data-orchester /var/lib/data-orchester/tmp
sudo cp data-orchester-X.Y.Z.jar /opt/data-orchester/data-orchester.jar
sudo cp application.properties /var/lib/data-orchester/
cd /var/lib/data-orchester
# The first administrator: the password in the environment, never on the command line
read -rs ORCHESTER_ADMIN_PASSWORD && export ORCHESTER_ADMIN_PASSWORD
sudo --preserve-env=ORCHESTER_ADMIN_PASSWORD java -jar /opt/data-orchester/data-orchester.jar identity-setup --local ADMIN
unset ORCHESTER_ADMIN_PASSWORD
sudo useradd --system --user-group --home-dir /var/lib/data-orchester --shell /usr/sbin/nologin data-orchester
sudo usermod -a -G dialout data-orchester   # the serial ports
sudo chown -R data-orchester:data-orchester /var/lib/data-orchester

Then have the init system run this as data-orchester, from /var/lib/data-orchester, and restart it when it stops:

java -Djava.io.tmpdir=/var/lib/data-orchester/tmp -jar /opt/data-orchester/data-orchester.jar

DataOrchester installs on macOS from the install package: one archive holding the DataOrchester jar, its configuration file application.properties and the install scripts. install.sh verifies the package, installs a private Java runtime, registers DataOrchester as a launchd daemon that starts at boot, creates the first administrator and starts it. It runs on macOS 14 or later, on Apple silicon and Intel.

The install script

To change a setting before installing - the port (8080 by default), the title, the language, the time zone - edit application.properties in the extracted directory first. Every key is in the configuration reference.

Before it changes anything, the script checks the jar and the Java runtime against the package's signed checksums.txt, with the release key pinned inside it, and stops with Nothing was changed if either does not match. Then it:

1. downloads Temurin 25, a Java runtime, from Adoptium, and verifies it the same way;
2. creates the service account, the program directory and the instance home, and copies application.properties into the home;
3. asks for the first administrator's password, at least 12 characters, twice;
4. writes the launchd daemon, starts it and waits until it answers;
5. prints the address to open.

Options

Option	Effect
--config FILE	Use this configuration file instead of the package's application.properties; on an upgrade, replace the home's copy with it
--admin ACCOUNT	The first local administrator, instead of install.admin-account (ADMIN)
--admin-password-file FILE	Read that administrator's password from the file's first line
--admin-no-password	Create the administrator without a password: whoever reaches the sign-in page first defines it. Only when you ask for it
--activation-code CODE	A licence activation code - letters, digits and dashes - redeemed at the first start; see Licence activation
--java PATH	Run on this Java 25 instead of a private runtime
--runtime FILE	The Temurin archive for this machine, for an install with no network; it is verified all the same
--unattended	Ask nothing: generate the password unless one is given
--uninstall [--purge]	Remove DataOrchester, and with --purge its data too; see Uninstalling

sh install.sh --help lists them as well. An unattended install that activates a licence:

sudo sh install.sh --unattended --activation-code ABCD-1234

The script's exit code, for automation:

Code	Meaning
0	Done
1	Refused; the message says why
2	A usage error in the options
3	Nothing to install for the administrator you asked for: one already exists

What it sets up

What	Where
Program: the jar and the Java runtime	/Library/DataOrchester
Instance home: application.properties, entities/, logs/, loggers/, instance/, tmp/, theme/	/Library/Application Support/DataOrchester, owned by the service account; instance/ is readable by it alone
Service	launchd daemon com.amtiri.dataorchester: starts at boot, before anyone signs in, and launchd starts it again whenever it stops
Account	_dataorchester, a hidden system account that cannot sign in
Daemon definition	/Library/LaunchDaemons/com.amtiri.dataorchester.plist, readable by root alone: it holds the activation code

Nothing Java-related on the machine changes: the runtime is DataOrchester's own. What each directory of the home holds is in the configuration reference.

First sign-in

Open the address the script printed, from this Mac or another machine on the network.

• You typed a password: sign in as ADMIN with it.
• The script generated one - with no terminal, or with --unattended: it printed it once, and kept it in /Library/DataOrchester/admin-password.txt, which only root can read. Sign in with it: the sign-in card then asks for a new password, which must differ from the generated one, before anything else is granted. The file is worthless from then on, and can be deleted.

The script hands the password to the jar's identity-setup in ORCHESTER_ADMIN_PASSWORD, never on a command line other processes could read. To install a directory or single sign-on provider instead of a local administrator, name its record in install.identity-provider before installing; see Sign-in and identity providers. Then carry on with After installing.

Running it

sudo launchctl print system/com.amtiri.dataorchester | grep state
sudo launchctl kickstart -k system/com.amtiri.dataorchester
sudo tail -f "/Library/Application Support/DataOrchester/logs/server.log"

• Settings: the instance reads /Library/Application Support/DataOrchester/application.properties at every start, not the package's copy. Edit it with sudo, then restart the daemon with launchctl kickstart -k.
• Unattended: restart the Mac once and check the daemon is running before anyone signs in - DataOrchester drives the plant with nobody at the keyboard.

Troubleshooting

Symptom	What to do
A checksum or signature message, then Nothing was changed	The package or the runtime is not what the release signed. Download it again, and verify it before extracting
could not download the runtime	No route to github.com. On a connected machine, download the Temurin JRE archive of the version the download page names - OpenJDK25U-jre_aarch64_mac_hotspot_25.0.4.1_1.tar.gz for 25.0.4.1+1 on Apple silicon, x64 in place of aarch64 on Intel, from Adoptium's temurin25-binaries releases on GitHub - and pass it with --runtime
DataOrchester did not answer within 180 seconds	Read /Library/Application Support/DataOrchester/logs/server.log
run as root	Run the script with sudo
Support asks for a self-check	/Library/DataOrchester/runtime/bin/java -jar /Library/DataOrchester/data-orchester.jar selfcheck proves the jar's libraries load on this machine

DataOrchester installs on Windows from the install package: one archive holding the DataOrchester jar, its configuration file application.properties and the install scripts. install.ps1 verifies the package, installs a private Java runtime, registers DataOrchester as a Windows service, creates the first administrator and starts it. It runs on Windows 10, Windows 11 and Windows Server 2019 or later, in Windows PowerShell 5.1 or PowerShell 7.

The install script

To change a setting before installing - the port (8080 by default), the title, the language, the time zone - edit application.properties in the extracted directory first. Every key is in the configuration reference.

install.ps1 is not Authenticode-signed, which is why it runs with -ExecutionPolicy Bypass: your check of the archive is what vouches for it. Before it changes anything, the script checks the jar and the Java runtime against the package's signed checksums.txt, with the release key pinned inside it, and stops with Nothing was changed if either does not match. Then it:

1. downloads Temurin 25, a Java runtime, from Adoptium, and verifies it the same way;
2. installs the program and the instance home, and registers the service;
3. asks for the first administrator's password, at least 12 characters, twice;
4. opens the port in Windows Firewall, starts the service and waits until it answers;
5. prints the address to open.

Options

Option	Effect
-Config FILE	Use this configuration file instead of the package's application.properties; on an upgrade, replace the home's copy with it
-Admin ACCOUNT	The first local administrator, instead of install.admin-account (ADMIN)
-AdminPasswordFile FILE	Read that administrator's password from the file's first line
-AdminNoPassword	Create the administrator without a password: whoever reaches the sign-in page first defines it. Only when you ask for it
-ActivationCode CODE	A licence activation code - letters, digits and dashes - redeemed at the first start; see Licence activation
-Java PATH	Run on this java.exe, a Java 25, instead of a private runtime
-Runtime FILE	The Temurin archive for this machine, for an install with no network; it is verified all the same
-Unattended	Ask nothing: generate the password unless one is given
-Uninstall, -Purge	Remove DataOrchester, and with -Purge its data too; see Uninstalling

Get-Help .\install.ps1 -Detailed describes them as well. An unattended install that activates a licence:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Unattended -ActivationCode ABCD-1234

The script's exit code, for automation:

Code	Meaning
0	Done
1	Refused; the message says why
2	A usage error in the options
3	Nothing to install for the administrator you asked for: one already exists

What it sets up

What	Where
Program: the jar and the Java runtime	C:\Program Files\DataOrchester
Instance home: application.properties, entities\, logs\, loggers\, instance\, tmp\, theme\	C:\ProgramData\DataOrchester, open to SYSTEM, the Administrators and the service only
Service	DataOrchester: starts automatically at boot, before anyone signs in, and restarts after a failure - after 5 s, 5 s, then 30 s. It runs the jar's windows-service command
Account	NT SERVICE\DataOrchester, a virtual account: no password to manage
Firewall	An inbound rule for the configured port, DataOrchester-HTTP
Activation code	The service's environment, which only SYSTEM, the Administrators and the service can read

Nothing Java-related on the machine changes: the runtime is DataOrchester's own. What each directory of the home holds is in the configuration reference.

First sign-in

Open the address the script printed, from this machine or another one on the network.

• You typed a password: sign in as ADMIN with it.
• The script generated one - with no console, or with -Unattended: it printed it once, and kept it in C:\Program Files\DataOrchester\admin-password.txt, which only administrators can read. Sign in with it: the sign-in card then asks for a new password, which must differ from the generated one, before anything else is granted. The file is worthless from then on, and can be deleted.

The script hands the password to the jar's identity-setup in ORCHESTER_ADMIN_PASSWORD, never on a command line other processes could read. To install a directory or single sign-on provider instead of a local administrator, name its record in install.identity-provider before installing; see Sign-in and identity providers. Then carry on with After installing.

Running it

Get-Service DataOrchester
Restart-Service DataOrchester
Get-Content C:\ProgramData\DataOrchester\logs\server.log -Tail 50 -Wait

• Settings: the instance reads C:\ProgramData\DataOrchester\application.properties at every start, not the package's copy. Edit it as an administrator, then Restart-Service DataOrchester.
• Unattended: reboot once and check the service is running before anyone signs in - DataOrchester drives the plant with nobody at the console.

Troubleshooting

Symptom	What to do
A checksum or signature message, then Nothing was changed	The package or the runtime is not what the release signed. Download it again, and verify it before extracting
no Java runtime is published for windows-aarch64	Temurin publishes no Java 25 runtime for Windows on arm64: install a Java 25 for arm64 yourself and pass its java.exe with -Java
could not download the runtime	No route to github.com. On a connected machine, download the Temurin JRE archive of the version the download page names - OpenJDK25U-jre_x64_windows_hotspot_25.0.4.1_1.zip for 25.0.4.1+1, from Adoptium's temurin25-binaries releases on GitHub - and pass it with -Runtime
DataOrchester did not answer within 180 seconds	Read C:\ProgramData\DataOrchester\logs\server.log
install.ps1 cannot be loaded ... not digitally signed	Group policy allows signed scripts only: install by hand, as below
Support asks for a self-check	& 'C:\Program Files\DataOrchester\runtime\bin\java.exe' -jar 'C:\Program Files\DataOrchester\data-orchester.jar' selfcheck proves the jar's libraries load on this machine

Installing by hand

A machine whose group policy runs signed scripts only refuses install.ps1. Install the jar by hand instead: the commands below are typed at the prompt, which that policy does not restrict, and set up what the script would. In an administrator PowerShell, from the extracted, verified package:

1. Install a Java 25, such as Eclipse Temurin 25, then name the paths:

   $java = '<your Java 25>\bin\java.exe'
   $programDir = 'C:\Program Files\DataOrchester'
   $homeDir = 'C:\ProgramData\DataOrchester'
   New-Item -ItemType Directory -Force $programDir, "$homeDir\tmp" | Out-Null
   Copy-Item data-orchester-X.Y.Z.jar "$programDir\data-orchester.jar"
   Copy-Item application.properties $homeDir
   

2. Create the first administrator, from the home. The password goes in ORCHESTER_ADMIN_PASSWORD, never on the command line:

   cd $homeDir
   $env:ORCHESTER_ADMIN_PASSWORD = [Net.NetworkCredential]::new('', (Read-Host -AsSecureString 'Password for ADMIN')).Password
   & $java "-Duser.dir=$homeDir" "-Djava.io.tmpdir=$homeDir\tmp" -jar "$programDir\data-orchester.jar" identity-setup --local ADMIN
   Remove-Item Env:ORCHESTER_ADMIN_PASSWORD
   

3. Register the service with the command line install.ps1 writes, under its own virtual account; limit the home to SYSTEM, the Administrators and the service; open the port; start it:

   $command = "`"$java`" --enable-native-access=ALL-UNNAMED `"-Duser.dir=$homeDir`" `"-Djava.io.tmpdir=$homeDir\tmp`" -jar `"$programDir\data-orchester.jar`" windows-service --home `"$homeDir`""
   New-Service -Name DataOrchester -DisplayName DataOrchester -BinaryPathName $command -StartupType Automatic
   sc.exe config DataOrchester obj= 'NT SERVICE\DataOrchester'
   sc.exe sidtype DataOrchester unrestricted
   sc.exe failure DataOrchester reset= 86400 actions= restart/5000/restart/5000/restart/30000
   icacls $homeDir /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' 'NT SERVICE\DataOrchester:(OI)(CI)M'
   icacls "$homeDir\*" /reset /T /C /Q
   New-NetFirewallRule -Name DataOrchester-HTTP -DisplayName 'DataOrchester (TCP 8080)' -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow
   Start-Service DataOrchester
   

Use the port application.properties sets, if not 8080. To upgrade an installation made by hand, stop the service, replace data-orchester.jar with the new release's jar, and start it again.

DataOrchester is also published as a container image, amtiri/data-orchester, for amd64 and arm64: the same jar as the install package, on Temurin 25. It suits a host already run with Docker, and a Linux without systemd.

Tags and signature

• Every release is tagged with its version, and the newest also as latest. Pin the version on a plant, so that a recreated container never upgrades by itself.
• The image is signed with cosign: cosign verify checks the signature against cosign.pub, published with each release, and fails if it does not match. The download page shows the release's digest.

The run command

read -s keeps the password - at least 12 characters - off the screen and out of the shell's history, and -e ORCHESTER_ADMIN_PASSWORD, by name alone, passes its value on from the shell, so it is never written in the command. Open http://<host>:8080/ and sign in as ADMIN. The instance listens on port 80 inside the container; -p maps it to the host port of your choice.

--init puts a small init process in front of Java, which passes on the stop signal and reaps any process that exits: without it, a container can refuse to stop.

Volumes

Four directories hold everything that must survive a recreated or upgraded container - mount all four:

Volume	Holds
/opt/orchester/entities	Your configuration: peers, modules, variables, schemas. An empty one gets the four built-in roles at start
/opt/orchester/logs	server.log and security.log
/opt/orchester/loggers	Time-series data recorded by logger modules
/opt/orchester/instance	The DataOrchester's identity and its licence. Without it, a recreated container is a new installation that has lost its licence

Nothing is copied into them from the image, which holds no configuration of its own. The container runs as the image's unprivileged account, orchester: named volumes, as above, take their ownership from the image, while a host directory mounted instead must be writable by that account - docker run --rm --entrypoint id amtiri/data-orchester:X.Y.Z prints its numeric id.

Configuration

Set the keys of application.properties through their environment variables, or mount a whole file at /opt/orchester/application.properties by adding this to docker run - the install package's copy lists every key with its default:

-v "$PWD/application.properties:/opt/orchester/application.properties:ro"

Where a key has a variable, the variable wins. The image sets APP_PORT=80, which overrides server.port: the instance always listens on 80 inside, and -p chooses the host's port. Logos and a stylesheet named by the appearance keys go in /opt/orchester/theme, which can be mounted read-only the same way. Every key is in the configuration reference.

Variable	Purpose
ORCHESTER_ADMIN_ACCOUNT	The first administrator's account, on a new installation; see After installing
ORCHESTER_ADMIN_PASSWORD	Their password. Without it, whoever reaches the sign-in page first defines it. Keep it out of version control
ORCHESTER_IDENTITY_PROVIDER	Instead of the two above: a provider record to install, such as a directory with its administrators
SITE_TRUSTED_PROXIES	The reverse proxy in front of the container, when there is one: IPv4 and IPv6 addresses, and IPv4 CIDR blocks, separated by commas
SITE_PUBLIC_BASE_URL	For single sign-on: the address browsers reach the container at, such as https://orchester.example.cl
DATAORCHESTER_ACTIVATION_CODE	A licence activation code, redeemed at the first start; see Licence activation
DATAORCHESTER_PORTAL_URL	The Amtiri portal the licence comes from; https://dataorchester.com unless Amtiri says otherwise
JDK_JAVA_OPTIONS	Java options, such as -Xmx2g

The set-up variables are read only while the installation has no identity provider, so they can stay set. See Sign-in and identity providers.

A read-only container

With a read-only root file system, give Java a writable temporary directory it may execute from: it unpacks the native libraries of SQLite and the serial ports there.

docker run --read-only --tmpfs /opt/orchester/tmp:exec ...

Minimal Compose example

services:
  data-orchester:
    image: amtiri/data-orchester:X.Y.Z
    ports:
      - "8080:80"
    volumes:
      - entities:/opt/orchester/entities
      - logs:/opt/orchester/logs
      - loggers:/opt/orchester/loggers
      - instance:/opt/orchester/instance
    environment:
      ORCHESTER_ADMIN_ACCOUNT: ADMIN
      # From an .env file kept out of version control.
      ORCHESTER_ADMIN_PASSWORD: ${ORCHESTER_ADMIN_PASSWORD}
      # Only when a reverse proxy fronts the container: its address or block.
      SITE_TRUSTED_PROXIES: ""
    restart: unless-stopped
    init: true

volumes:
  entities:
  logs:
  loggers:
  instance:

To upgrade, change the tag and run docker compose up -d: the container is recreated on the same volumes. See Upgrading.

Reaching the web UI

Once the service is running (see the install guide for your platform), open a browser to the machine's address on the configured port. You will see the sign-in card if the first authenticator was configured during installation, and No authenticator configured if it was not.

The first administrator

Data Orchester has no default account. The first authenticator - and its administrator - is configured when the installation is set up, in one of three ways:

• ORCHESTER_ADMIN_ACCOUNT, and optionally ORCHESTER_ADMIN_PASSWORD, in the service's environment: a local administrator account.
• ORCHESTER_IDENTITY_PROVIDER: the path of a provider record - a directory or single sign-on provider, with its administrators.
• java -jar data-orchester-X.Y.Z.jar identity-setup --local ACCOUNT or identity-setup --provider FILE, run from the instance home, with the password in ORCHESTER_ADMIN_PASSWORD: the jar's own command, which the install scripts run for you. Restart the service afterwards. Installations from a Gradle distribution call it bin/IdentitySetup.

Set-up acts only while no provider exists and never overwrites an account. Without a password, the administrator's first sign-in - the account and an empty password - opens a screen to define one, and nothing is granted until they do. See Sign-in and identity providers.

No authenticator configured

If the web UI shows No authenticator configured instead of a sign-in card, no identity provider can take a sign-in yet. Configure the first one as above and restart the service. On an installation that had one, look for PROVIDER_DISABLED in logs/security.log: a provider is left out when an environment variable its secret names is not set.

Activating at install

A new DataOrchester can take its licence as it is installed, with nothing to copy into it afterwards: give the licence's activation code to the install script, or to the container.

Installation	How
Linux, macOS	sudo sh install.sh --activation-code CODE
Windows	powershell -ExecutionPolicy Bypass -File .\install.ps1 -ActivationCode CODE
Container	DATAORCHESTER_ACTIVATION_CODE=CODE in its environment

The code comes with the licence: shown when you claim a free licence, and sent to your organization's contact address when you buy one. The licence, in your licences page, also offers Install a DataOrchester for this licence to the organization's owners and administrators: the commands for Linux and macOS, Windows and Docker, with the code already in them. It appears once a release is published, while the licence has a code nobody has redeemed and no DataOrchester bound to it.

The DataOrchester redeems the code at its first start, while its engine runs the two hours of that start: it collects its licence and loads its configuration again under it, so everything the licence enables applies at once. Once a licence is in force, later starts redeem nothing. A code that cannot be redeemed is logged — the code itself never is — and the engine runs its two hours and stops: restart the service or the container once the portal can be reached.

The install scripts keep the code in the service's own environment, out of application.properties and out of reach of other accounts, and an upgrade keeps it there. A container keeps instance/ on a persistent volume, like entities/, logs/ and loggers/: it holds the DataOrchester's identity and its licence.

Next steps

• Getting started
• Sign-in and identity providers
• Licence activation
• Configuration reference

An upgrade replaces the application and nothing else: your configuration, your data, the DataOrchester's identity and its licence all stay where they are.

Before you start: back up

Back up the instance home before every upgrade, without exception — at least these:

• application.properties
• entities/
• logs/
• loggers/
• instance/ — the DataOrchester's identity and its licence, which exist nowhere else

The instance home is /var/lib/data-orchester on Linux, /Library/Application Support/DataOrchester on macOS and C:\ProgramData\DataOrchester on Windows; a container keeps it in its volumes. An in-place upgrade replaces the program only; it must never touch the home. Taking the backup regardless costs you a few minutes and protects against the one bad release that breaks this assumption.

In-place upgrade

1. Download the newer package from the download page, and verify it before extracting it, as for a new installation: Windows, macOS, Linux.
2. Extract it and run its script the same way: sudo sh install.sh, or powershell -ExecutionPolicy Bypass -File .\install.ps1 in an administrator PowerShell. It finds the installation by itself, and:
   • verifies the package and the Java runtime before it changes anything;
   • stops the service, and replaces the jar and the runtime;
   • keeps the home's application.properties, and lists the settings the new release has that your file does not set — the new package's application.properties says what each one does;
   • keeps every other directory of the home, the administrators and the activation code;
   • starts the service again, and waits until it answers.
3. Confirm the version shown in the UI matches what you installed.
4. Open the licence pane and confirm the licence is in force: Licensed, with no warning. If it is not, see Your licence after the upgrade below.
5. Confirm your existing dashboards, modules and peers all still load and report data as before.

To replace the home's configuration on purpose, run the script with --config FILE (-Config FILE on Windows): that file becomes the home's application.properties. An installation that runs on a Java of its own (--java) keeps it.

A container upgrades by pulling the new tag and recreating the container on the same four volumes, with the same variables:

docker pull amtiri/data-orchester:X.Y.Z
docker stop data-orchester && docker rm data-orchester

Then docker run it again with the new tag, as in Install with Docker — or, with Compose, change the tag and run docker compose up -d.

Your licence after the upgrade

An upgrade keeps the licence: the DataOrchester starts on the licence it held, and nothing has to be registered again.

The exception is a release that stops trusting the key your licence was signed with. The licence pane then says The licence on this machine was signed with a key this version of DataOrchester no longer trusts. The engine starts all the same, but it runs only the two hours of that start until it holds a licence signed with the current key:

• Online — keep the portal reachable while the DataOrchester starts. It collects a new licence by itself, usually within seconds, and restarts once, shortly after starting, when its new licence arrives: it loads its configuration again, so everything the licence enables applies at once. If it collects none, restore its connection and select Check for licence: an engine that stopped in the meantime starts again by itself once the licence arrives.

• Air-gapped — replace the offline key. Plan the maintenance window around it: the engine runs for two hours from the start after the upgrade, and if the new key is not registered by then, it stops until it is.

  1. In the licence pane of the upgraded DataOrchester, select Copy DO Id. Copy it after the upgrade: a DO Identifier copied before it gets a key the new version cannot use.
  2. On the licence in the portal, select Replace offline key, paste the DO Identifier and copy the new key.
  3. In the licence pane, select Register offline and paste the key. An engine that stopped starts again by itself; one still in its two hours restarts once, loading its configuration again.

  The button reads Register offline, not Register new key: a licence signed with a key that is no longer trusted is no licence, so the DataOrchester holds none.

If instance/ was lost, restore it from the backup. Without a backup, an online DataOrchester collects its licence again at its next check, and an air-gapped one needs its offline key registered again: Copy offline key on the licence, then Register offline in the licence pane. If the licence pane shows a different install ID than before, the identity was lost as well: restore instance/, entities/ and loggers/ from the backup before doing anything else.

When licensing stops an upgraded engine

The release that runs every start for two hours also changes when licensing stops an engine. Once upgraded, a DataOrchester:

• starts whatever its licence says, and runs for two hours from every start; after that, only a licence in force keeps it running — see How licensing works;
• with an online licence, stops seven days after the portal last confirmed that licence: plan any work that cuts it off from the portal around those seven days;
• stops within about four hours of being cleared in the portal.

A DataOrchester not yet upgraded keeps the rules it was built with: it does not start without a licence, and an online one stops at the end of its lease plus its grace — up to about two weeks after it last reached the portal, or after it was cleared. Whichever version runs, a lease or offline key signed since the grace was shortened carries 7 days of grace after its expiry; an offline key cut before keeps its 14 days.

What must not happen

• Configuration should not need re-entering after an upgrade.
• No entity file should be silently rewritten by the new version on first load — if you see every entity file's modification time change right after an upgrade, that's a bug, not expected behaviour.

Rolling back

If something goes wrong, run the previous release's install script the same way: it puts its own jar and runtime back, and keeps the home. Restore entities/, logs/ and loggers/ from the backup you took before the upgrade only if the new version wrote anything unexpected to them. A same-version reinstall never requires restoring the backup; only do so if you have a concrete reason to believe the new version altered your data. A container rolls back by running the previous tag on the same volumes.

A version from before a signing-key change does not trust licences signed with the new key. An online DataOrchester collects one it trusts at its next check, for as long as the portal still signs for that version; an air-gapped one needs instance/ restored from the backup taken before the upgrade. Correct the machine's clock before you roll back: an older version refuses to start when the clock is behind the time the newer one trusted.

Uninstalling removes DataOrchester's service and program, and keeps its instance home - the configuration, the history and the licence identity - so that a mistaken uninstall, or a planned reinstall, destroys nothing. Deleting the data as well is a separate, deliberate step.

With the install script

Run the install script with --uninstall, from any extracted package of the installed version or a later one:

sudo sh install.sh --uninstall

On Windows, in an administrator PowerShell:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall

It stops the service, and removes:

Platform	Removed
Linux	The systemd unit data-orchester, /etc/data-orchester with the service's secrets file, and /opt/data-orchester
macOS	The launchd daemon com.amtiri.dataorchester and its plist, and /Library/DataOrchester
Windows	The DataOrchester service with its environment, its firewall rule, and C:\Program Files\DataOrchester

The instance home stays where it was, and on Linux and macOS so does the service account. Installing the same or a later release again picks the home up as it was left - with the same install.home-dir, if the home was moved.

Removing the data too

Only when the data is no longer wanted:

1. Give the licence back first, so it can run another machine: see Giving a licence back in Licence activation.

2. Take a backup if there is any chance you will want this data later: this step cannot be undone.

3. Uninstall with --purge (-Purge on Windows):

   sudo sh install.sh --uninstall --purge
   

   It asks you to type the instance code - the name at the top of the Orchester panel, or ORCHESTER if it was never set - then deletes the instance home, and on Linux and macOS the service account too. It needs someone at a terminal to type the code: run unattended, it keeps the home.

Purging is never the default, and never happens without that code: removing a plant's licensed configuration should never be a side effect of a routine removal.

Containers

docker compose down, or docker rm, removes the container; its volumes stay unless you pass -v or --volumes. To delete the data as well, give the licence back first, then remove the four volumes: docker compose down --volumes, or docker volume rm with their names.

An installation made by hand

Stop and remove the service you registered, and delete the jar. On Windows, in an administrator PowerShell:

Stop-Service DataOrchester
sc.exe delete DataOrchester
Remove-NetFirewallRule -Name DataOrchester-HTTP
Remove-Item -Recurse 'C:\Program Files\DataOrchester'

The instance home is left for you to keep or delete.