On this page

Komodo builds Docker images by running docker build and pushing the result to a configured image registry.

Dockerfile Sources

Komodo supports three ways of providing the Dockerfile and build context:

1. Write in the UI — define the Dockerfile contents directly in Komodo. Supports variable and secret interpolation.
2. Files on host — point to an existing Dockerfile and build context already present on the builder machine. Set files_on_host = true and use build_path / dockerfile_path to specify the paths.
3. Git repo — clone a repository containing the Dockerfile. This is the default mode. Configure repo, branch, and optionally git_account for private repos.

Configuration

[[build]]
name = "my-app"
[build.config]
builder = "builder-01"
repo = "myorg/my-app"
branch = "main"
git_account = "my-user"
image_registry = [\
  { domain = "ghcr.io", account = "my-user", organization = "my-org" }\
]

Config fields

Image Versioning and Tagging

Komodo uses a major.minor.patch versioning scheme. By default, each build auto-increments the patch number. You can control exactly which tags are pushed using the following options:

Tag types

All three are enabled by default. Disable any combination to control which tags are pushed.

Image tag postfix

The image_tag field appends a postfix to all generated tags. This is useful for multi-platform or variant builds:

When image_tag is set, an additional pure tag is also pushed: :aarch64.

Custom image name

By default, the build's name is used as the image name. Set image_name to override this, e.g. if the build name doesn't match the desired image name on the registry.

Manual versioning

Set auto_increment_version = false to manage the version field yourself. The major and minor versions are always set manually — only the patch auto-increments.

Image Registry

Komodo supports pushing to any Docker-compatible registry. Configure accounts in Providers.

A build can push to multiple registries simultaneously. The image_registry field accepts a list — each entry specifies a domain, account, and optional organization:

[build.config]
image_registry = [\
  { domain = "ghcr.io", account = "my-user", organization = "my-org" },\
  { domain = "docker.io", account = "my-user" },\
]

The first registry in the list is used by default when a Deployment is connected to the Build.

note

GitHub access tokens must have the write:packages permission to push to GHCR.

When a Build is connected to a Deployment, the Deployment inherits the Build's registry credentials by default. If the builder's account isn't available to the Deployment's server, select a different account in the Deployment config.

Multi-platform builds (Buildx)

To build for multiple platforms (e.g. ARM + x86), set up Docker Buildx on the builder:

docker buildx create --name builder --use --bootstrap
docker buildx install   # makes buildx the default for `docker build`

Then pass the target platforms in the Build's Extra Args:

--platform linux/amd64,linux/arm64

Builders

A Builder resource defines where builds run. Any Server connected to Komodo can be used as a builder, but building on production servers is not recommended.

Server builder

Point the builder at an existing Server running the Periphery agent.

AWS EC2 builder

Komodo can launch a temporary EC2 instance for each build and shut it down when finished.

[[builder]]
name = "builder-01"
[builder.config]
type = "Aws"
params.region = "us-east-2"
params.instance_type = "c5.2xlarge"
params.ami_id = "ami-xxxxxxxxxxxxxxxxxx"
params.subnet_id = "subnet-xxxxxxxxxxxxxxxxxx"
params.key_pair_name = "ssh-key"
params.assign_public_ip = true ## Required for outbound internet access unless you have network gateway.
params.use_public_ip = true ## Setting 'false' uses the private IP (when Komodo Core is in same subnet).
params.security_group_ids = ["sg-xxxxxxxxxxxxxxxxxx"]
params.user_data = """
#!/bin/bash
curl -sSL \
   https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | \
  HOME=/root python3 - --version=v2.X.X
"""

To create the AMI:

1. Launch an EC2 instance and install Docker:

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
systemctl enable docker.service containerd.service

2. Create an AMI from the instance in the AWS console.
3. Create a security group and ensure it allows inbound access on port 8120 from Komodo Core.

The instance user_data will install the Periphery agent as the instance starts up, and Komodo Core will then connect and build the image.