Komodo on Ubuntu 24.04 on Azure User Guide

Overview

Komodo is an open source build and deployment platform for Docker hosts. From one web interface you define stacks and deployments, build images from your own git repositories, run scheduled procedures, and watch the state of everything you have deployed as it changes. It replaces the habit of keeping compose files on a server and driving them over SSH, and it keeps a record of what was deployed, when, and by whom.

This image delivers Komodo 2.3.3 on Ubuntu 24.04 as a complete, self-contained appliance. Backed by 24/7 cloudimg support.

What is included:

• Komodo Core — the API and web interface, reachable only through an encrypted front door
• Komodo Periphery — the agent that creates, starts and destroys containers on this VM, already connected to Core
• FerretDB over a PostgreSQL 17 document engine — the database beneath Komodo, reachable from neither the network nor any other container
• nginx terminating TLS on port 443 with a certificate generated on your own VM, installed from the Ubuntu archive so it keeps receiving security updates
• Docker Engine from the Ubuntu archive, for the same reason
• alpine:3.22, already present, so your first deployment works without reaching a registry
• On-VM self tests you can run at any time, each of which is itself tested against a known bad input first

This image ships with no shared password. On first boot your VM generates its own administrator password, its own database password, its own session signing key and its own TLS certificate, writes them to a file only root can read, and refuses to start Komodo until it has. Self registration is switched off, so nobody can create an account simply by visiting the page.

Please read this before you connect it to anything you care about. Komodo manages Docker on this VM, and the agent that does so necessarily has full control of the container engine — which is equivalent to administrative access to the machine. That is inherent to what Komodo is, not a property of this image. Whoever holds the Komodo administrator credential can run any container here. Give Komodo its own VM, which is exactly what this image is, and treat its password as you would treat root on this machine.

The data layer avoids the Server Side Public License entirely: Komodo speaks the MongoDB wire protocol, and this image serves it with FerretDB (Apache-2.0) over the DocumentDB PostgreSQL extension (MIT). No MongoDB component is installed.

Komodo, Docker, FerretDB and PostgreSQL are trademarks of their respective owners. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them. This image packages the unmodified open source software, which is distributed under the GNU General Public License v3.0.

Prerequisites

• An Azure subscription
• A VM size with at least 2 vCPUs and 8 GiB of memory. Standard_B2ms is the recommended size and is what this image is tuned for: four containers, one of them a PostgreSQL cluster, plus room for the containers you deploy.
• Inbound TCP 443 open to the addresses you will administer Komodo from, and 22 for SSH. Nothing else needs to be open.
• An SSH key pair

Step 1: Deploy from the Azure Marketplace

Find Komodo on Ubuntu 24.04 LTS in the Azure Marketplace, choose Create, and select Standard_B2ms (or larger). On the Networking tab allow inbound 443 and 22. Leave everything else at its default and create the VM.

Step 2: Deploy from the Azure CLI

az vm create \
  --resource-group my-resource-group \
  --name my-komodo \
  --image cloudimg:komodo-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Then open the two ports you need:

az vm open-port --resource-group my-resource-group --name my-komodo --port 443 --priority 1001

Step 3: Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4: Confirm the appliance is running

Komodo is four containers plus an encrypted front door. All of it starts automatically at boot.

systemctl is-active docker nginx komodo-postgres komodo-ferretdb komodo-core komodo-periphery

sudo docker ps --format 'table {{.Names}}\t{{.Status}}'

Each of those four images is pinned to exact content rather than to a moving tag, and none of them is ever fetched at runtime.

Step 5: Your VM's own administrator password

This image was not shipped with a password. The one below was generated on this VM, on its first boot, before Komodo was allowed to start.

sudo sed -E 's/^(KOMODO_ADMIN_PASSWORD=).*/\1REDACTED/' /root/komodo-credentials.txt

That file is 0600 root:root. To read the real password:

sudo grep '^KOMODO_ADMIN_PASSWORD=' /root/komodo-credentials.txt | cut -d= -f2-

The address to sign in at is in the same file:

sudo grep '^KOMODO_URL=' /root/komodo-credentials.txt | cut -d= -f2-

Step 6: Sign in to the web interface

Open https://<KOMODO_ADDRESS>/ in a browser. The certificate was generated on your VM, so your browser will warn that it is not signed by a public authority — that is expected for an appliance reached by IP address. Sign in with the user <KOMODO_ADMIN_USER> and the password from Step 5.

Once you are in, the home view lists every resource Komodo knows about. On a new appliance that is an empty slate with one server: this VM.

If you would rather put a real certificate in front of it, replace /etc/ssl/komodo/komodo.crt and /etc/ssl/komodo/komodo.key and reload nginx. Keep the private key 0600 root:root.

Step 7: What the network can reach

Only two ports on this VM answer from off the machine: SSH, and the encrypted Komodo front door. The database, the document engine and the agent are reachable from neither the network nor from the containers Komodo deploys.

sudo ss -Hltn | awk '{print $4}' | sort -u

The bundled checker asserts that set by equality, rather than by looking for a handful of unwanted ports:

sudo /usr/local/sbin/komodo-port-check.sh

And this confirms no MongoDB component is present anywhere — not on the VM, not in any of the four container images, and not in the unit files that start them:

sudo /usr/local/sbin/komodo-no-sspl-assert.sh

Step 8: Nobody can sign themselves up

Komodo's own default is to allow self registration, and to let the first person who visits an appliance with no administrator claim it. This image closes that, and reports it honestly to the browser so no sign-up button is ever drawn:

ADDR="$(sudo grep '^KOMODO_ADDRESS=' /root/komodo-credentials.txt | cut -d= -f2-)"
curl -s --cacert /etc/ssl/komodo/komodo.crt --resolve "${ADDR}:443:127.0.0.1" \
  -H 'Content-Type: application/json' \
  -d '{"type":"GetLoginOptions","params":{}}' \
  "https://${ADDR}/auth/login"
echo

registration_disabled is true and every external login provider is false. Your VM also re-checks this for itself on every boot: if the administrator account is ever missing, it stops the front door rather than leaving an open sign-up on a machine that manages containers.

systemctl is-active komodo-postboot-verify.service

Komodo limits sign-in attempts to 5 in any 15 second window. That is a feature, not a limitation of this image, and it applies to the checks below as well — if you run several of them back to back and one reports a refusal, wait twenty seconds and run it again.

Step 9: Prove the whole posture in one command

sudo /usr/local/sbin/komodo-verify.sh

This asserts, on the running appliance: the four images still match the content they were pinned to, the off-VM listening set is exactly SSH and 443, no MongoDB component is present, the database and the agent publish no port, self registration is closed, Komodo Core is published only on the loopback interface, the encrypted front door forwards the live-update websocket, containers are denied the Azure instance metadata service, the certificate names this VM rather than the machine the image was built on, and the administrator credential recorded on this VM is the one that actually opens it — while a wrong one is refused.

It finishes by feeding every one of its own offline checks a deliberately bad input and requiring each to fail on it, because a check that cannot fail proves nothing.

For the heavier version, which also stands up a deliberately insecure throwaway Komodo on its own temporary database to prove the sign-up check can actually see an open sign-up, run sudo /usr/local/sbin/komodo-selftest.sh --customer-vm --full. It takes a few minutes and removes everything it created.

Step 10: Deploy your first container

In the web interface choose Deployments, then New Deployment. Give it a name, pick the server called Local — that is this VM — and set the image to alpine:3.22, which is already present. Then press Deploy.

The same thing is available from the command line, and this is the check the image ships for it. It signs in through the front door exactly as you did, creates a deployment, runs it, reads the container's own output back out of Komodo, and then removes both the deployment and the container:

sudo /usr/local/sbin/komodo-deploy-probe.sh

It reports the container's own output rather than a status code on purpose: a Komodo that created a deployment and silently ran nothing would return success for every call in that sequence.

Step 11: What the containers you deploy can and cannot reach

A container Komodo deploys is, by construction, code you chose to run. Ordinary networking works normally — it can resolve names and reach the internet, so images pull and packages install:

sudo docker run --rm alpine:3.22 sh -c 'nslookup ghcr.io >/dev/null 2>&1 && echo "name resolution works" || echo "name resolution is broken"'

What it cannot reach is the Azure instance metadata service, which is where a virtual machine's own cloud credentials are handed out. Without that boundary, "can deploy a container here" would quietly mean "holds this subscription's identity":

sudo docker run --rm alpine:3.22 sh -c 'wget -q -T 5 -O /dev/null http://169.254.169.254/metadata/instance 2>/dev/null && echo "metadata reachable" || echo "metadata unreachable, as intended"'

The rules are installed as a systemd unit and reapplied whenever Docker restarts:

sudo /usr/local/sbin/komodo-egress-filter.sh check

The VM itself keeps its own access to that service, which is how it learned its public address on first boot. Only containers are filtered.

Step 12: Where your data lives, and how to back it up

Everything Komodo stores — every resource you define, every user, every update record — lives in two Docker volumes:

sudo docker volume ls --format '{{.Name}}'

The compose files, repositories and build contexts Komodo manages for you live on the VM at /etc/komodo:

ls /etc/komodo

Komodo writes dated database backups into /etc/komodo/backups, which is mounted into Core. Back up that directory and the two volumes together and you can rebuild this appliance elsewhere.

Your per-VM secrets live in /etc/komodo-secrets, mode 0700, deliberately mounted into no container:

sudo stat -c '%a %U:%G %n' /etc/komodo-secrets

Step 13: Routine administration

Change the administrator password from the web interface under Settings, or through the API with the UpdatePassword request. Do that before you connect Komodo to anything important, and keep self registration switched off.

To add a second person, create the account from Settings as the administrator and enable it there. Leaving self registration off means accounts are only ever created by someone who is already signed in.

Security updates for Ubuntu, nginx and the container engine install themselves:

systemctl is-enabled unattended-upgrades.service

Step 14: Upgrade

The four container images are pinned to exact content, so nothing changes underneath you. To move to a newer Komodo, edit the image reference in /etc/systemd/system/komodo-core.service and /etc/systemd/system/komodo-periphery.service, then sudo systemctl daemon-reload and restart the two units. Take a backup first, and read the Komodo release notes: the database schema can change between minor versions.

For a clean upgrade path with none of that work, deploy the next cloudimg image release and restore your backup into it.

Troubleshooting

The browser warns about the certificate. Expected: the certificate was generated on your VM and is not signed by a public authority. Replace it as described in Step 6 if you are putting a hostname in front of the appliance.

A sign-in is refused and you are sure the password is right. Komodo limits sign-in attempts to 5 in any 15 second window. Wait twenty seconds and try again.

The web interface loads but nothing updates. The live-update websocket is not getting through. Check that nothing between you and the VM is stripping the upgrade header, and confirm the front door still forwards it:

grep -c 'proxy_set_header Upgrade' /etc/nginx/sites-available/komodo

The front door is not answering at all. The post-boot check stops nginx if this VM's administrator credential ever stops working, rather than leaving an unprotected Komodo running. Read why, then recover:

sudo journalctl -u komodo-postboot-verify.service -n 20 --no-pager

Komodo will not start after a reboot. Every unit is gated on first boot having completed. Confirm it did:

ls -l /var/lib/cloudimg/komodo-firstboot.done /var/lib/cloudimg/komodo.bootstrap-ready

A deployment will not start. Read what the agent actually reported:

sudo journalctl -u komodo-periphery.service -n 30 --no-pager

Support

cloudimg provides 24/7 support for this image: deployment, connecting repositories and registries, stack and deployment design, webhooks and alerting, backups, scaling to additional managed hosts, and upgrades. Contact support@cloudimg.co.uk.