Running Koios as a Service

This is the last step in getting Koios running. It makes Koios start when the machine does and restart by itself if it stops, without anyone logged in.

Docker Engine must be installed first. See Installing Docker Engine if you have not done that yet.

Why a Service File?

You can start Koios by typing a docker run command, and it works — but only until something interrupts it. A container started by hand has three problems on a machine nobody is watching:

• It dies with your session. Close the terminal or drop the remote connection and the container can go with it.
• It does not come back after a power cut. The machine reboots, and Koios simply is not running. Nobody finds out until someone notices missing data — which on a plant machine can be days.
• Nothing restarts it if it fails. Any container can stop unexpectedly. Without something watching, it stays stopped.

For an industrial system, all three are unacceptable. Data collection that quietly stops is worse than data collection that was never set up, because people are relying on it.

A service file hands responsibility to systemd, the part of Linux that starts and supervises background programs. Writing one file gets you:

It is a text file you write once. The rest of this page writes it.

The file holds the same docker run command you would otherwise type, plus instructions telling systemd when to run it. Nothing is hidden — read it at any time to see exactly what starts.

Create the Service File

Create the systemd service file:

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

Paste the following content. Toggle options to customize the service, then copy the result:

[Unit]
Description=Ai-Ops, Koios Docker Run Service
After=docker.service
Requires=docker.service

[Service]
TimeoutStartSec=10
Restart=always
ExecStartPre=-/usr/bin/docker stop %n
ExecStartPre=-/usr/bin/docker rm %n
ExecStart=/usr/bin/docker run --rm --name=%n --network host \
  --mount source=koios_data_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_data_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_media,target=/var/www/koios/media \
  --mount source=koios_logs,target=/var/www/koios/logs \
  --mount source=koios_certs,target=/var/www/koios/certs \
  --mount source=koios_license,target=/var/www/koios/license \
  --mount source=koios_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:latest
ExecStop=/usr/bin/docker stop %n

[Install]
WantedBy=default.target

For production it is recommended to pin a specific version tag (e.g. v1.0.0) so that upgrades are intentional. See Updating Koios.

Enable and Start the Service

Three commands, each doing a different job:

sudo systemctl daemon-reload

Tells systemd to re-read its configuration and notice the file you just created. Run this again after any future edit to the file, or your change is ignored.

sudo systemctl enable docker.koios.service

Marks Koios to start automatically on boot. This is what survives a power cut.

sudo systemctl start docker.koios.service

Starts it now, without waiting for a reboot.

enable and start are separate and you need both — one schedules Koios for future boots, the other runs it now. Restart-on-failure comes from Restart=always in the file. Between them the three cases are covered: crash, reboot, and right now.

First start takes longer than later ones — Koios prepares its databases before it begins serving. Give it a few minutes before concluding something is wrong.

Check Status

sudo systemctl status docker.koios.service

View Logs

journalctl -u docker.koios.service -f

Press Ctrl+C to stop following the log output.

Firewall

The --network host flag means the container binds directly to host ports 443 (HTTPS) and 80 (HTTP). If the host has a firewall enabled (e.g. ufw), allow those ports:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

If you have customised the ports via HTTPS_PORT or HTTP_PORT environment variables, open those ports instead. See Environment Variables for details.

Alternative: Explicit Port Mapping

If you prefer not to use host networking, replace --network host with explicit port mappings in the service file. Change the ExecStart line to include -p 443:443 -p 80:80 instead of --network host. To run several Koios instances on one host, see Running Multiple Instances.

If Koios has to reach industrial devices, --network host is the better choice — it lets the container talk to them directly. With explicit port mapping you may need further -p flags for device communication.

First Access

Once the service is running, open a browser and navigate to:

https://<your-server-ip>

Your browser may show a certificate warning for the built-in self-signed certificate. This is expected. Accept the warning to proceed.

To replace it with a certificate your browsers trust, upload a CA-signed certificate at System > Certificates once you are logged in — see Certificates — or place one on the certificates volume before first boot, see Environment Variables.

Log in with the default credentials:

• Username: admin
• Password: koios

About Docker Volumes

Koios stores all of its data in seven named Docker volumes: the configuration database, time-series database, uploaded files, license, certificates, logs, and secrets. These volumes live on the host and persist independently of the container, so your data survives container restarts, updates, and re-deployments.

Docker automatically creates any missing volumes when the container first starts, so no manual setup is required. If you prefer to create them explicitly upfront, you can run:

docker volume create koios_data_postgres
docker volume create koios_data_influxdb
docker volume create koios_media
docker volume create koios_logs
docker volume create koios_certs
docker volume create koios_license
docker volume create koios_secrets

See Backing Up Docker Volumes for a description of what each volume contains.

What's Next

• Licensing Koios: activate your Koios license
• Environment Variables: customize network ports, TLS, performance, logging, and more
• Updating Koios: upgrade to a new version safely