Installation Guide#

This guide covers all the ways to install OS Image Composer and its prerequisites.

Table of Contents#

Prerequisites#

  • OS: Ubuntu 24.04 (recommended; other standard Linux distributions may work but are not validated)

  • Go: Version 1.24.0 or later — see Go installation instructions

Development Build (Go)#

For development and testing purposes, build directly with Go. The binary is placed in the repo root as ./os-image-composer.

# Build the tool (output: ./os-image-composer)
go build -buildmode=pie -ldflags "-s -w" ./cmd/os-image-composer

# Build the live-installer (required for ISO images)
go build -buildmode=pie -o ./build/live-installer -ldflags "-s -w" ./cmd/live-installer

# Or run without building
go run ./cmd/os-image-composer --help

Note: Development builds show default version information (e.g., Version: 0.1.0, Build Date: unknown). This is expected.

Including Version Information in Dev Builds#

To embed version metadata via ldflags:

VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "dev")
COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
BUILD_DATE=$(date -u '+%Y-%m-%d')

go build -buildmode=pie \
  -ldflags "-s -w \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.Version=$VERSION' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.Toolname=Image-Composer' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.Organization=Open Edge Platform' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.BuildDate=$BUILD_DATE' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.CommitSHA=$COMMIT'" \
  ./cmd/os-image-composer

# Required for ISO images
go build -buildmode=pie \
  -o ./build/live-installer \
  -ldflags "-s -w \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.Version=$VERSION' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.Toolname=Image-Composer' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.Organization=Open Edge Platform' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.BuildDate=$BUILD_DATE' \
    -X 'github.com/open-edge-platform/os-image-composer/internal/config/version.CommitSHA=$COMMIT'" \
  ./cmd/live-installer

Production Build (Earthly)#

For reproducible production builds with automatic version injection. The binary is placed in ./build/os-image-composer.

# Default build (output: ./build/os-image-composer)
earthly +build

# Build with custom version metadata
earthly +build --VERSION=1.2.0

Install via Debian Package#

For Ubuntu and Debian systems, OS Image Composer can be installed as a .deb package with proper package management.

Build the Debian Package#

# Build with default parameters (latest git tag, amd64)
earthly +deb

# Build with custom version
earthly +deb --VERSION=1.2.0

The package is created in the dist/ directory as os-image-composer_<VERSION>_<ARCH>.deb.

Install the Package#

# Recommended — automatically resolves dependencies
sudo apt install <PATH>/os-image-composer_1.0.0_amd64.deb

Alternatively, using dpkg:

sudo apt-get update
sudo apt-get install -y bash coreutils unzip dosfstools xorriso grub-common
sudo dpkg -i dist/os-image-composer_1.0.0_amd64.deb
# Optional bootstrap tools:
sudo apt-get install -y mmdebstrap || sudo apt-get install -y debootstrap

Tip: If dpkg -i reports dependency errors, run sudo apt-get install -f to resolve them.

Verify Installation#

dpkg -l | grep os-image-composer
os-image-composer version

Package Contents#

Path

Description

/usr/local/bin/os-image-composer

Main executable

/etc/os-image-composer/config.yml

Global configuration

/etc/os-image-composer/config/

OS variant configuration files

/usr/share/os-image-composer/examples/

Sample image templates

/usr/share/doc/os-image-composer/

README, LICENSE, CLI specification

/var/cache/os-image-composer/

Package cache storage

Package Dependencies#

Required:

  • bash, coreutils, unzip, dosfstools, xorriso, grub-common

Recommended (installed if available):

  • mmdebstrap (preferred, version 1.4.3+ required)

  • debootstrap (alternative)

Important: mmdebstrap version 0.8.x (included in Ubuntu 22.04) has known issues. For Ubuntu 22.04, install version 1.4.3+ manually — see mmdebstrap instructions.

Uninstall#

# Remove package (keeps config files)
sudo dpkg -r os-image-composer

# Remove package and config files
sudo dpkg --purge os-image-composer

Image Composition Prerequisites#

Before composing images, install these additional tools:

ukify#

Combines kernel, initrd, and UEFI boot stub to create signed Unified Kernel Images (UKI).

mmdebstrap#

Downloads and installs Debian packages to initialize a chroot.

  • Ubuntu 23.04+: Available in system repositories (version 1.4.3+)

  • Ubuntu 22.04: The repository version (0.8.x) will not work — install 1.4.3+ manually per the mmdebstrap instructions

  • Alternative: debootstrap can be used for Debian-based images

Next Steps#