---
title: "Running Koios as a Service"
slug: "setting-up-the-koios-service"
updated: 2025-06-04T15:21:33Z
published: 2025-06-04T15:21:33Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-op.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Koios as a Service

This step is very important to have a great experience with Koios. We are going to go over how to create a service that will manage starting and stopping Koios for you which will give you the following benefits:

- Correctly mounts critical volumes for persistent configuration, certificates, logging, historical data, and modeling files.
- Auto-restarts the service upon a reboot.

### Creating a Service File

Ubuntu systemd service files can be stored inside of `/etc/systemd/system/`, this is where we are going to create a service file that will start and stop Koios. Use your favorite terminal text editor to create a service file, in this case we are using nano. Make sure to include `sudo` to ensure permissions:

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

Next, paste the following into nano in the terminal:

```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 \
                                                          aiopinc/koios:latest

ExecStop=/usr/bin/docker stop %n

[Install]
WantedBy=default.target
```

> [!NOTE]
> Versioning
> 
> If using a specific version, make sure to change the `latest` tag to your version.

For nano, use `ctrl+O` and then press `Enter` to save the file, and `ctrl+X` to close.

> [!WARNING]
> Service file change
> 
> If you need to make any changes to the service file, make sure to run `sudo systemctl daemon-reload` after, this will update the service with the latest changes.

### Enabling and Running the Service

To enable the new service file, run:

```shell
sudo systemctl enable docker.koios.service
```

Now that the service is enabled, you can start, stop, or restart the service using:

```shell
sudo service docker.koios stop
```

```shell
sudo service docker.koios start
```

```shell
sudo service docker.koios restart
```

When ready run `sudo service docker.koios start` to start the service initially.

### Checking the Service Status

Next use the following to check the service status:

```shell
sudo service docker.koios status
```

The bottom line will say `Starting koios_ui koios_ui ...done` when the service is completely running.

### Troubleshooting the Service

If you are not seeing the `koios_ui ...done` message and the service is continually restarting, you may have an issue with your service file. Ensure that the last `ExecStart` command contains a valid image name. For example, if you are using the latest Docker Hub image, the last line should contain `aiopinc/koios:latest` and you should be able to run `docker image ls` in the command line and see an image with a repository name of `aiopinc/koios` and a tag name of `latest`.

If you have made a change to the service file, make sure to stop the service using `sudo service docker.koios stop` and then call `sudo systemctl daemon-reload` to load the latest file. Next, start the service again using `sudo service docker.koios start`.

If you still are seeing the service is failing, try using `journalctl -u docker.koios.service` to view a detailed log of the service.

### Accessing the User Interface

If the service is running successfully, you should be able to visit the Koios user interface. On the host machine, open your preferred web browser and type in `localhost`.

> [!WARNING]
> Trusted Certificate
> 
> You will receive a warning about the server using a self signed certificate, depending on the browser, there will be some button or link allowing you to continue.

#### Default Login Credentials

At the login screen you will be prompted for a username and password. If this is your first time accessing Koios, the username and password will be the default:

- **Username:**admin
- **Password:**koios

### What’s Next

Now that we’re up and running, we will walk through licensing Koios.