Running Koios as a Service

For production deployments, run Koios as a systemd service. This ensures Koios starts automatically on boot and restarts on failure. Docker Engine must be installed before continuing — see Installing Docker Engine if you haven't done this yet.

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

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

The Restart=always directive ensures the service restarts automatically if the container exits unexpectedly or the host reboots.

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.

First Access

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

https://<server-ip>

Your browser may show a certificate warning for the self-signed SSL certificate — this is expected. Accept the warning to proceed.

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