---
title: "Running Koios as a Service"
description: "Configure Koios to run as a systemd service"
source_url: https://ai-ops.com/docs/installation/running-as-a-service
---

# 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](https://ai-ops.com/docs/installation/installing-docker.md) if you haven't done this yet.

## Create the Service File

Create the systemd service file:

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

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

```ini
[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
```

Optional flags (off by default — add to the command to enable):

- Stream logs to stdout: `-e LOG_STDOUT_ENABLED=true`
- OpenTelemetry collector: `-e OTEL_COLLECTOR_ENABLED=true`
- Disable TLS: `-e ENABLE_TLS=false`

For production it is recommended to pin a specific version tag (e.g. `v1.0.0`) so that upgrades are intentional — see [Updating Koios](https://ai-ops.com/docs/updates/general.md).

## Enable and Start the Service

```bash
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

```bash
sudo systemctl status docker.koios.service
```

## View Logs

```bash
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:

```bash
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](https://ai-ops.com/docs/installation/environment-variables.md) 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`.

> [!WARNING] Device Communication
> If Koios needs to connect to industrial devices (OPC-UA, Modbus), `--network host` is recommended so the container can reach devices directly on the host network. With explicit port mapping, you may need additional `-p` flags for device communication ports.

## First Access

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

```text
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`

> [!CAUTION] Change Default Password
> Change the default admin password immediately after your first login.

## 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:

```bash
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](https://ai-ops.com/docs/installation/backup-restore.md) for a description of what each volume contains.

## What's Next

- [Licensing Koios](https://ai-ops.com/docs/installation/licensing.md) — activate your Koios license
- [Environment Variables](https://ai-ops.com/docs/installation/environment-variables.md) — customize network ports, TLS, performance, logging, and more
- [Updating Koios](https://ai-ops.com/docs/updates/general.md) — upgrade to a new version safely