Building and deploying containers with Komodo on Ubuntu

Introduction

Komodo is a self-hosted tool for building and deploying Docker containers across one or many servers from a single web interface. It has two parts: Core, which runs the database, the API, and the dashboard, and Periphery, a small agent that runs on every server you want Komodo to manage. You configure deployments, stacks (Docker Compose projects), and builds in the UI, and Core tells the right Periphery agent to carry them out.

This tutorial installs Core together with a Periphery agent on the same server, then deploys a container to it from the dashboard. The same server that runs Core is registered automatically, so you have something to deploy to right away.

Komodo is free and open source (GPL-3.0). This was tested on a fresh Ubuntu 26.04 LTS server with Komodo v2.2.0.

Prerequisites

• One server (a fresh Ubuntu 24.04 or 26.04 install is fine)
• Root access, or a user with sudo

Example terminology

• Username: holu
• IPv4 address: 10.0.0.1

Replace them with your own values. All commands are run with sudo.

Step 1 - Install Docker

Komodo and everything it deploys run as containers. Install Docker with the official script, which works on Ubuntu 24.04 and 26.04:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Add your user to the docker group:

sudo usermod -aG docker holu

Exit the server and reconnect to update the groups.

Step 2 - Download the Komodo files

Komodo ships ready-made Compose files. Get the MongoDB variant and its environment file:

sudo mkdir -p /opt/komodo
cd /opt/komodo
sudo wget https://raw.githubusercontent.com/moghtech/komodo/main/compose/mongo.compose.yaml
sudo wget https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env

The Compose file defines three services: mongo, core (image ghcr.io/moghtech/komodo-core), and periphery (image ghcr.io/moghtech/komodo-periphery). Core's dashboard is published on port 9120.

Step 3 - Set the configuration

All settings live in compose.env. Generate a few secrets first:

openssl rand -hex 16   # database password
openssl rand -hex 16   # webhook secret
openssl rand -hex 24   # JWT secret

Open /opt/komodo/compose.env and change at least the following. Use your server's IP or domain for KOMODO_HOST, and pick a real admin password:

KOMODO_HOST=http://10.0.0.1:9120
KOMODO_DATABASE_USERNAME=komodo
KOMODO_DATABASE_PASSWORD=<database-password>
KOMODO_INIT_ADMIN_USERNAME=admin
KOMODO_INIT_ADMIN_PASSWORD=<your-admin-password>
KOMODO_WEBHOOK_SECRET=<webhook-secret>
KOMODO_JWT_SECRET=<jwt-secret>
KOMODO_FIRST_SERVER_NAME=Local

KOMODO_INIT_ADMIN_USERNAME / KOMODO_INIT_ADMIN_PASSWORD make Core create the first admin on startup, so you don't register through the browser. KOMODO_FIRST_SERVER_NAME registers the bundled Periphery agent under that name, which is why you get a ready-to-use server called Local.

Open the dashboard port in the firewall:

sudo ufw allow 9120/tcp

Step 4 - Start Komodo

Start the stack, passing both the Compose file and the env file:

docker compose -p komodo -f mongo.compose.yaml --env-file compose.env up -d

Watch Core come up:

docker logs komodo-core-1 -f

Wait for these lines, then press CTRL+C to stop following:

INFO CoreStartup: Creating init admin user...
INFO CoreStartup: Successfully created init admin user.
INFO Server starting on http://[::]:9120

The Periphery agent connects to Core on its own. In its log you'll first see a connection refused while Core is still starting, then a success — that retry is normal:

docker logs komodo-periphery-1

WARN Failed to connect to websocket ... Connection refused
INFO Logged in to Komodo Core core:9120 websocket as Server Local

Step 5 - Log in and check the server

Open http://<your-server-ip>:9120 and log in with the admin username and password you set in Step 3.

Go to Servers in the sidebar. The Local server is listed with its version and a State of OK, which means the Periphery agent is connected and Komodo can deploy to it.

Step 6 - Deploy a container

Open Deployments and click New Deployment. Give it a name like hello-nginx and create it. You land on its configuration page.

Set two things:

• Select Server: choose Local.
• Image: type a Docker image, for example nginx:alpine.

Click Save and confirm the change. Then click Deploy and Confirm. Komodo pulls the image on the server and starts the container; the deployment's state switches to running.

Check it from the server's command line:

docker ps --filter name=hello-nginx

NAMES         IMAGE          STATUS
hello-nginx   nginx:alpine   Up 5 seconds

The container is running, managed entirely from the dashboard. From the same page you can view its logs, stop it, redeploy it, or destroy it.

Step 7 - Add more servers

To manage another machine, install only the Periphery agent on it — there's no need for a second Core. Komodo can run Periphery as a container or as a system binary; the official guide covers both at https://komo.do/docs/connect-servers.

Once Periphery is running on the other host, go to Servers in the dashboard, click New Server, and enter that machine's address. When it connects it appears alongside Local, and you can target your deployments, stacks, and builds at it.

Conclusion

You installed Komodo, confirmed the bundled Periphery agent was connected, and deployed a running container from the web UI. Beyond single containers, Komodo manages full Docker Compose stacks, builds images from Git repositories, and reacts to webhooks for automatic redeploys — all from the same dashboard. Adding more Periphery agents lets you run all of it across your whole fleet from one place.

License: MIT