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. To run several instances side by side, give each one explicit port mappings and its own volume set.

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 and its own seven volumes:

# Instance A, reachable at https://<host>:8443
docker run -d --name koios-a \
  -p 8443:443 \
  --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:latest

# Instance B, reachable at https://<host>:8444
docker run -d --name koios-b \
  -p 8444:443 \
  --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:latest

Each instance is then reached at https://<host>:<port>, for example https://<host>:8443 and https://<host>:8444. Log in to each one separately; every instance has its own admin account and its own license.

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. You rarely need to map 80, since you connect to each instance by its HTTPS port directly.
• 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. Use --name koios-a, koios-b, and so on, so Docker can tell them apart.

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 explicit port and volume set from above:

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

[Service]
Restart=always
RestartSec=5
ExecStartPre=-/usr/bin/docker rm -f koios-a
ExecStart=/usr/bin/docker run --rm --name koios-a \
  -p 8443:443 \
  --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:latest
ExecStop=/usr/bin/docker stop 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 four things in every copy: the unit file name (docker.koios-b.service), the container name (koios-b), the host port (-p 8444:443), and the volume set (koios_b_*). Keeping these four distinct is what lets the instances coexist on one host.

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, firewall notes, and version pinning.

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 host:port from the console's Instances page and monitor them all without signing into each one.