Running Koios as a Service

  • Updated on Jun 4, 2025
  • Published on Sep 24, 2024
  • 3 minute(s) read
Prev Next

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:

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

Next, paste the following into nano in the terminal:

[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

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.

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:

sudo systemctl enable docker.koios.service

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

sudo service docker.koios stop
sudo service docker.koios start
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:

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.

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.