Installing Docker Engine

Koios ships as a Docker container, so the machine needs Docker Engine. This page installs it. Allow about 10 minutes.

What Docker Is, Briefly

A container is an application packaged with everything it needs to run — libraries, configuration, supporting services — as one unit. Docker Engine is what runs it.

For you this means Koios installs as a single download with no dependencies to resolve, upgrades by swapping that download for a newer one, and cannot conflict with anything else on the machine. Your data lives outside the container, so replacing it does not touch your data.

You do not need to learn Docker to run Koios. The handful of commands you need are in these pages.

Docker Desktop is the graphical application for Windows and macOS; Docker Engine is the server version, and it is what you want here. Desktop on a server is not appropriate and is licensed differently.

Install It

Run these in order, on the Koios machine. You can paste them if you connected over SSH in the previous step.

1. Remove any conflicting packages

Ubuntu carries older, unofficial Docker packages that conflict with the current one. Clear them out — this succeeds whether or not any were installed:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  sudo apt-get remove -y $pkg
done

Do not install the docker.io package

Ubuntu's own docker.io package is an older, separately maintained build. Install Docker's official packages as below — that is what Koios is tested against.

2. Add Docker's software repository

This tells Ubuntu where to fetch Docker from, and installs the key used to verify what it downloads:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Then add the repository itself. This is one long command — paste it whole:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

It fills in your architecture and Ubuntu version automatically, so it is the same command on every machine.

3. Install Docker

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

This downloads several hundred megabytes and takes a few minutes.

Let Your User Run Docker

Docker commands need administrator rights. Rather than prefixing every command with sudo, add yourself to the docker group:

sudo usermod -aG docker $USER

The change applies at your next login. Rather than logging out, pick it up in the current session:

newgrp docker

Group membership is administrator-equivalent

Anyone in the docker group can obtain full control of the machine. That is inherent to Docker, not specific to Koios. On a machine several people log into, leave them out of the group and let them use sudo instead.

Check It Worked

docker --version

That should report a version number.

docker run hello-world

Docker downloads a small test image and runs it. It prints a paragraph beginning Hello from Docker! and exits. That confirms Docker can download images, run containers, and reach the internet.

If it fails with a permissions error mentioning the Docker socket, the group change has not taken effect — run newgrp docker again, or log out and back in.

Make Docker Start on Boot

Ubuntu normally enables this during installation. Confirm it:

sudo systemctl is-enabled docker

If that reports anything other than enabled:

sudo systemctl enable --now docker

Without this, Koios does not come back after the machine restarts.

Machines Without Internet Access

The steps above download from the internet. On a machine with no internet access, ask your Ai-OPs representative for the offline installation package — it carries Docker's packages and their dependencies, matched to your Ubuntu version.

The packages are specific to an Ubuntu release and processor architecture, so say which you have. Confirm both with:

. /etc/os-release && echo "$VERSION_ID $(uname -m)"

That prints something like 26.04 x86_64. On a Raspberry Pi or other ARM machine it reports aarch64 instead.

Reference

The commands above follow Docker's own installation instructions for Ubuntu, which are the authority if you need a variation this page does not cover — a different Linux distribution, or a site that requires a proxy.

What's Next

Getting the Koios Image: download Koios itself

Time Synchronization Getting the Koios Image