Most teams outgrow single-host Docker tooling the moment a second server appears. You end up SSH-ing between boxes, hunting for the machine that runs a given stack, and copying compose files around by hand. Komodo is the fix we reach for: a self-hosted control plane that manages containers, compose stacks, builds, and Git-driven deployments across every server you own, from one dashboard. It is open source, it is genuinely free for multi-server use, and that last point matters more than it used to now that Portainer has moved role-based access and SSO behind its Business tier. Below, we install Komodo on a fresh Ubuntu server and grow it from one box into a managed fleet.
The walkthrough targets Ubuntu 26.04 and 24.04, wires Komodo behind Nginx with a real certificate, and connects a second machine so you can see the multi-host story in practice. We built everything on Ubuntu 26.04 (kernel 7.0) with Docker Engine 29.6, and ran the identical steps on Ubuntu 24.04, in July 2026 against Komodo v2.2. The commands are Docker-based, so they behave the same on both LTS releases.
Prerequisites
Komodo Core itself is light. What actually sizes the box is MongoDB, which holds all of Komodo’s state, plus the polling load of however many servers and containers you point it at. For a homelab or a handful of servers, 2 vCPU and 2 GB of RAM is a comfortable floor, and the test box for this guide ran 2 vCPU with 4 GB, which is a floor for following along rather than a production recommendation. If you plan to manage dozens of hosts with frequent stats polling, give Core 4 GB or more and put its data on SSD-backed storage.
- A server running Ubuntu 26.04 or 24.04 with sudo access. Tested on both.
- A CPU that exposes the AVX instruction set. MongoDB 5.0 and later require it. On a bare-metal or modern cloud instance this is a non-issue; on a Proxmox or older hypervisor VM it is the single most common reason the stack fails to start, and we cover the fix below.
- A domain name with an A record pointing at the server if you want HTTPS, which you do for anything past a quick test.
- Docker Engine and the Compose plugin. We install these in the next step.
How Komodo is put together
Before the commands, it helps to know what you are deploying, because Komodo splits into pieces on purpose. There are three parts. Core is the brain: it serves the web UI and the API, stores everything in MongoDB, and decides what runs where. Periphery is a small agent that runs on every server you want to manage, including the Core host itself; it is the process that actually talks to the local Docker socket. MongoDB is the database behind Core.
The reason this matters: adding a new server to Komodo is not a plugin or an agent-in-agent. You install one Periphery agent on that host, and Core connects to it. That is the whole multi-host model, and it is why Komodo scales past the single box that tools like Dockge stop at. The trade-off compared with Portainer is that Komodo asks you to think in terms of resources (stacks, deployments, builds) rather than raw containers, which pays off once you manage more than one host.
Install Docker Engine and the Compose plugin
Komodo ships as container images, so the only real dependency is Docker. Add Docker’s official repository. The command reads your release codename automatically, so the same block works on 26.04 and 24.04:
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
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.listInstall the engine, the CLI, and the Compose and Buildx plugins:
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginConfirm both the engine and the Compose plugin are present:
docker --version
docker compose versionOn the test hosts this printed the current stable engine and the v5 Compose plugin, identical on both releases:
Docker version 29.6.2, build dfc4efb
Docker Compose version v5.3.1If you are setting up a brand-new host and want the base steps in isolation, the Docker Compose on Ubuntu guide covers the same ground with a bit more detail.
Install Komodo Core with Docker Compose
Komodo publishes ready-made compose files. Create a directory, then pull the MongoDB variant of the compose file and its environment file:
sudo mkdir -p /opt/komodo /etc/komodo/backups
cd /opt/komodo
sudo curl -fsSL https://raw.githubusercontent.com/moghtech/komodo/main/compose/mongo.compose.yaml -o compose.yaml
sudo curl -fsSL https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env -o compose.envEverything reader-specific lives in one file, compose.env, which is the design choice that keeps this tidy: you edit one place, not the compose file. Generate two random secrets first, one for signing JWTs and one for webhook authentication, and keep the output handy:
openssl rand -hex 32
openssl rand -hex 24Now open the environment file:
sudo vim /opt/komodo/compose.envSet the values below. Give the database a real password, paste the two secrets you just generated, and choose the admin username and password you will log in with. KOMODO_HOST is used to build OAuth and webhook URLs, so set it to the address you will actually reach Komodo on (we switch it to the HTTPS domain later):
KOMODO_DATABASE_USERNAME=komodo
KOMODO_DATABASE_PASSWORD=Change_This_DB_Password
KOMODO_HOST=http://10.0.1.50:9120
KOMODO_INIT_ADMIN_USERNAME=admin
KOMODO_INIT_ADMIN_PASSWORD=Change_This_Admin_Password
KOMODO_JWT_SECRET=paste_the_openssl_rand_hex_32_here
KOMODO_WEBHOOK_SECRET=paste_the_openssl_rand_hex_24_here
KOMODO_FIRST_SERVER_NAME=LocalThe admin account is created from those two variables on the very first launch. Bring the stack up. Passing the env file to the up command is required, because the compose file reads those values at deploy time:
sudo docker compose -p komodo --env-file compose.env up -dCompose pulls three images and starts them. Check that all three are up:
sudo docker compose -p komodo --env-file compose.env psYou should see Core, MongoDB, and the local Periphery agent running, with Core published on port 9120 and Periphery listening internally on 8120:
NAME SERVICE STATUS PORTS
komodo-core-1 core Up 6 hours 0.0.0.0:9120->9120/tcp, [::]:9120->9120/tcp
komodo-mongo-1 mongo Up 6 hours 27017/tcp
komodo-periphery-1 periphery Up 6 hours 8120/tcpA quick check against the Core logs confirms the version and that it bound cleanly:
sudo docker logs komodo-core-1 2>&1 | grep "Komodo Core version"The startup line reports the running release:
INFO CoreStartup: Komodo Core version: v2.2.0If MongoDB exits with “Illegal instruction”
This is the one failure worth calling out because it trips up self-hosters constantly. If Core keeps restarting and its logs show it cannot reach mongo:27017, look at the MongoDB container’s logs:
sudo docker logs komodo-mongo-1If you see the message below, the CPU your VM is presenting to the guest does not expose AVX, which recent MongoDB requires:
WARNING: MongoDB 5.0+ requires a CPU with AVX support, and your current system does not appear to have that!
Illegal instruction (core dumped)On a Proxmox VM the fix is to change the guest CPU type from the default kvm64 to host, which passes the physical CPU’s instruction set through, then start the VM again. The equivalent exists on most hypervisors. If you genuinely cannot get AVX, Komodo also publishes a FerretDB compose variant that runs on PostgreSQL instead of MongoDB, and it has no such requirement; swap mongo.compose.yaml for ferretdb.compose.yaml in the download step above.
Open the Komodo dashboard and sign in
Browse to the server on port 9120. Komodo greets you with a login screen rather than an open signup, because the admin account already exists from the environment file:
Sign in with the admin username and password you set. The dashboard opens on a summary of your fleet: server health, the resources you have defined, and a quick view of recent activity. With a fresh install you have one healthy server, the local one, and Komodo’s default maintenance procedures already in place:
That green ring is the whole point of the tool. Every server you connect reports its health here, and anything unhealthy surfaces at the top before you go looking.
Put Komodo behind Nginx with HTTPS
Port 9120 is fine for a first look, but Komodo drives real deployments and holds real credentials, so it belongs behind TLS. The clean approach is an Nginx reverse proxy with a Let’s Encrypt certificate. Komodo uses WebSockets for the dashboard’s live views, so the proxy has to pass those through, which is the one detail people miss. This vhost only fronts browser traffic to Core on port 9120. The link between Core and the Periphery agents is separate and does not run through it.
Point an A record for your chosen name at the server, open ports 80 and 443, then set a variable so the rest of the section is copy-paste clean:
export SITE_DOMAIN="komodo.example.com"Install Nginx and Certbot:
sudo apt-get install -y nginx certbot python3-certbot-nginxCreate the site file:
sudo vim /etc/nginx/sites-available/komodo.confAdd the server block below. The Upgrade and Connection headers are what keep Komodo’s live views working through the proxy. Leave the placeholder for now; we substitute your real domain in the next command:
server {
listen 80;
server_name SITE_DOMAIN_HERE;
location / {
proxy_pass http://127.0.0.1:9120;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
proxy_send_timeout 300s;
}
}Swap the placeholder for your domain, enable the site, and reload Nginx:
sudo sed -i "s/SITE_DOMAIN_HERE/${SITE_DOMAIN}/" /etc/nginx/sites-available/komodo.conf
sudo ln -s /etc/nginx/sites-available/komodo.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginxIssue the certificate. The Nginx plugin uses the HTTP-01 challenge, which works with any DNS provider as long as port 80 is reachable, and it rewrites the vhost for TLS and redirects for you:
sudo certbot --nginx -d "${SITE_DOMAIN}" --non-interactive --agree-tos --redirect -m [email protected]If the server sits on a private network with no inbound port 80, use the DNS-01 challenge with your provider’s Certbot plugin instead; the Nginx reverse proxy with Let’s Encrypt walkthrough shows that path end to end. Finally, tell Komodo its real address by editing KOMODO_HOST in compose.env to https://komodo.example.com and recreating Core:
cd /opt/komodo
sudo docker compose -p komodo --env-file compose.env up -dManage containers and add more servers
Once you are in, the Containers view is the fastest way to see the payoff. It lists every container across every connected server, with state, image, network, and ports, and it is populated the moment Core comes up because the local Periphery agent reports the Komodo containers themselves:
The Servers page is where the multi-host model lives. Your Core host shows up as the first server, and adding another is a two-part move: install the Periphery agent on the new host, then connect it to Core with an onboarding key.
On the new server, install Docker exactly as above, then add the Periphery agent. Komodo’s setup script installs it as a systemd service. On a fresh install the agent listens on port 8120 over HTTPS with a self-signed certificate, which is worth knowing because it rules out a plain http:// address later:
curl -fsSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | sudo python3Komodo v2 authenticates agents with a public and private key pair rather than the older shared passkey, and it bootstraps that with an onboarding key. In the UI open Settings, switch to the Onboarding tab, click New Onboarding Key, and create one. Copy the value it shows you, because it is displayed once.
Point the agent at Core in outbound mode and pass that onboarding key. Re-run the setup script with the connection flags, using your Core HTTPS address and any name you like for the server:
curl -fsSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | sudo python3 - \
--core-address="https://komodo.example.com" \
--connect-as="$(hostname)" \
--onboarding-key="paste_the_onboarding_key_here"The agent generates its own key pair, dials Core, and sends only its public key, which Core stores so the new server shows up in your Servers list. Onboarding keys are reusable and only needed for that first connection, and the agent’s private key never leaves the box. If you would rather have Core reach into the agent instead, register the server in the UI with the address https://SERVER_IP:8120, since HTTPS is what the default agent serves. Either way, a stack you define once can then be deployed to whichever server you choose, and you can automate the surrounding workflow with the patterns in the managing Docker containers with Ansible guide.
The cost angle: Komodo against Portainer and Dockge
Where Komodo earns its place is the intersection of price and reach. Dockge is a pleasant single-host compose UI, but it stops at one machine, so a second server means a second Dockge. Portainer manages many hosts well, but its Business tier is where role-based access control, OIDC single sign-on, and registry management now live, and those are exactly the features a team needs the day more than one person touches production. Komodo gives you multi-host management, RBAC, OIDC, Git-driven deployments, and a built-in build system in the open-source edition, with no per-node or per-seat charge.
In practice this means the decision is rarely about the dashboard looking nicer. It is about whether you want deployment history, access control, and fleet-wide visibility without a licence conversation as you grow. Run it on the smallest box that has AVX, keep Core behind TLS, put a real password on Mongo, and add servers as Periphery agents. That setup has carried far more than a homelab, and nothing about it asks you to pay as the fleet gets bigger.
