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. To run several Koios instances on one host, see Running Multiple Instances.

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