Running Multiple Instances

You can run more than one Koios container on a single host, for example to separate lines, sites, or test environments on shared hardware. Each instance keeps its own database, history, certificates, and license in its own set of named volumes, so the instances stay fully isolated.

The one thing that has to change from a single-instance install is networking. The recommended --network host flag binds the container directly to host ports 443 and 80, so a second instance started the same way would fail to bind. Changing its HTTPS_PORT and HTTP_PORT is not enough either: each instance also runs its own databases, and under host networking those collide too. To run several instances side by side, give each one explicit port mappings and its own volume set.

Give Each Instance Its Own Address

Before creating anything, decide the address people will use for each instance: its own hostname, such as koios-a.plant.example and koios-b.plant.example, both pointing at this machine through DNS or a hosts-file entry, or its own IP address on the machine.

This matters because a browser treats every port on one address as the same site. If two instances are opened as https://<host>:8443 and https://<host>:8444 in the same browser, signing in to one breaks live logs, network diagnostics, log downloads, and trend export in the other. With a distinct hostname or address per instance, each keeps its own sign-in.

Each instance's built-in certificate lists that address through KOIOS_TLS_SAN, so set it before the instance first starts. Changing it later replaces the certificate: browsers ask again, and an Admin Console that monitors the instance needs you to sign in to it again.

Map Each Instance to a Unique Port

Replace --network host with -p mappings and pick a distinct host port for each instance's HTTPS port (443). Give every instance its own container name, hostname, and seven volumes, and pin the same version tag you intend to run:

# Instance A, reachable at https://koios-a.plant.example:8443
docker run -d --name koios-a --hostname koios-a --stop-timeout 60 -e KOIOS_STOP_TIMEOUT=60 \
  -p 8443:443 \
  -e KOIOS_TLS_SAN=koios-a.plant.example,192.168.1.50 \
  --mount source=koios_a_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_a_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_a_media,target=/var/www/koios/media \
  --mount source=koios_a_logs,target=/var/www/koios/logs \
  --mount source=koios_a_certs,target=/var/www/koios/certs \
  --mount source=koios_a_license,target=/var/www/koios/license \
  --mount source=koios_a_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:v1.2.5

# Instance B, reachable at https://koios-b.plant.example:8444
docker run -d --name koios-b --hostname koios-b --stop-timeout 60 -e KOIOS_STOP_TIMEOUT=60 \
  -p 8444:443 \
  -e KOIOS_TLS_SAN=koios-b.plant.example,192.168.1.50 \
  --mount source=koios_b_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_b_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_b_media,target=/var/www/koios/media \
  --mount source=koios_b_logs,target=/var/www/koios/logs \
  --mount source=koios_b_certs,target=/var/www/koios/certs \
  --mount source=koios_b_license,target=/var/www/koios/license \
  --mount source=koios_b_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:v1.2.5

Log in to each one separately; every instance has its own admin account and its own license, activated like any single install.

A few rules keep the instances isolated:

• A unique host port per instance. Only one container can own a given host port. Map the container's 443 to a different host port for each instance.
• A unique volume set per instance. Each container needs its own seven volumes (koios_a_*, koios_b_*, and so on). Never share a volume between instances, as doing so will corrupt data.
• A unique container name and hostname. Set both before the first start. The hostname is written into the instance's OPC-UA client certificate when it is first created, so it is how an OPC-UA server's trust list tells your instances apart. Changing it later means regenerating that certificate and trusting it again on every server. See OPC-UA Certificates.
• The instance's own names in its certificate. KOIOS_TLS_SAN lists the hostname and address people use to reach the instance, so the built-in HTTPS certificate matches them. See Environment Variables.
• Time to shut down. --stop-timeout 60 gives each instance up to 60 seconds to stop its services and databases cleanly, even when a reboot stops every instance at once, and -e KOIOS_STOP_TIMEOUT=60 tells Koios it has that long. An instance stops as soon as it has shut down. Without them, Docker allows 10 seconds, and the services get 5 of them. The unit below also passes -t 60 to each docker stop, so a container started before the flag was added stops cleanly too.
• Do not map port 80. Its redirect sends browsers to port 443 on the host, which here is another instance or nothing. Connect to each instance by its HTTPS port.

Size the Host for Every Instance

Each instance runs its own databases and services, so resources add up. Budget the System Requirements figures for each instance and give the host their sum. Three instances on one virtual machine need roughly three times the memory of one; the 8 GB starting point on Creating the Virtual Machine is for a single instance.

Run Each Instance as a Service

Most deployments run each instance as its own systemd service so it starts on boot and restarts on failure. Give every instance its own unit file, named for the instance (for example docker.koios-a.service).

Create the unit for the first instance:

sudo nano /etc/systemd/system/docker.koios-a.service

Paste a unit that carries the same settings from above:

[Unit]
Description=Koios (instance A)
After=docker.service
Requires=docker.service

[Service]
Restart=always
RestartSec=5
ExecStartPre=-/usr/bin/docker stop -t 60 koios-a
ExecStartPre=-/usr/bin/docker rm koios-a
ExecStart=/usr/bin/docker run --rm --name koios-a --hostname koios-a --stop-timeout 60 -e KOIOS_STOP_TIMEOUT=60 \
  -p 8443:443 \
  -e KOIOS_TLS_SAN=koios-a.plant.example,192.168.1.50 \
  --mount source=koios_a_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_a_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_a_media,target=/var/www/koios/media \
  --mount source=koios_a_logs,target=/var/www/koios/logs \
  --mount source=koios_a_certs,target=/var/www/koios/certs \
  --mount source=koios_a_license,target=/var/www/koios/license \
  --mount source=koios_a_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:v1.2.5
ExecStop=/usr/bin/docker stop -t 60 koios-a

[Install]
WantedBy=default.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable docker.koios-a.service
sudo systemctl start docker.koios-a.service

Then repeat for each additional instance, changing every value that names the instance: the unit file name (docker.koios-b.service), the container name and hostname (koios-b), the host port (-p 8444:443), its names in KOIOS_TLS_SAN, and the volume set (koios_b_*).

Check any instance with systemctl status docker.koios-a.service, and follow its logs with docker logs -f koios-a. See Running Koios as a Service for the single-instance walkthrough and firewall notes.

Upgrade One Instance at a Time

Pin a version tag in every unit, as above, rather than latest. With latest, pulling a new image upgrades every instance the next time it restarts — including after a power cut — all at once and without a backup you chose to take.

If an instance's unit was written before v1.2.5, first bring its stop settings in line with the unit above: add --stop-timeout 60 -e KOIOS_STOP_TIMEOUT=60 to its ExecStart line and -t 60 to its ExecStop line, and replace the ExecStartPre line that runs docker rm -f with the two ExecStartPre lines shown. Then run sudo systemctl daemon-reload, so the stops for its backup and its upgrade are clean.

To upgrade an instance, back it up, change the tag in its unit file, then:

sudo docker pull aiopinc/koios:<new-version>
sudo systemctl daemon-reload
sudo systemctl restart docker.koios-a.service

Confirm it is healthy before moving to the next. Each instance takes its own pre-upgrade backup on first start. Read the upgrade guide for the target version first; see Updating Koios.

When an instance first starts on v1.2 after an earlier version, it creates a new built-in HTTPS certificate. Browsers ask once more, and for an instance already connected to the Admin Console, open its connection settings in the console and sign in to it again so the console pins the new certificate.

Copying an Instance's Setup

Do not create an instance by restoring another instance's backup into it. A restore brings the whole system across, including its license and certificates, so the two would share one license and one identity. To reuse devices, tags, or models, export them from one instance and import them into the other; see Importing & Exporting Devices.

When a start-up message suggests a volume name, it shows the single-instance names such as koios_secrets. On a multi-instance host, substitute that instance's own volume, such as koios_b_secrets, before running any command it suggests.

Manage the Fleet from One Place

Once several instances are running, the Koios Admin Console gives you a single view of their health, service state, and licenses. Connect each instance by its hostname and port from the console's Instances page and monitor them all without signing into each one.