isocreator is a Deno-powered image customization tool for repeatable infrastructure builds. It creates customized Ubuntu Server ISOs and mutates raw disk images, including balenaOS/Raspberry Pi style boot partitions, from declarative YAML configuration.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What It Builds

Ubuntu Server ISO images with NoCloud cloud-init data.
ISO images from cached Ubuntu downloads, local source files, or explicit source URLs.
WiFi network configuration for first boot.
User accounts, SSH keys, packages, commands, files, locale, timezone, and arbitrary cloud-init directives.
Custom boot scripts copied into the extracted ISO tree.
Direct filesystem mutations with writeFile, copyFile, and ensureDir.
Raw disk images from .img, .img.xz, or .zip sources.
balenaOS/BaseOS boot partition metadata such as config.json, NetworkManager connections, and baseos/baserunner.env.

The CLI is distributed as a compiled binary. The source also exports the builder classes for Deno/source usage.

Installation

Install the released binary:

curl -sSL https://code.foss.global/serve.zone/isocreator/raw/branch/main/install.sh | sudo bash

Install through the npm package wrapper with pnpm:

pnpm add --global @serve.zone/isocreator

The package wrapper downloads the platform-specific binary during postinstall.

System Requirements

Ubuntu ISO builds require ISO tooling:

sudo apt install xorriso syslinux-utils

Raw image mutation requires libguestfs and archive tooling:

sudo apt install libguestfs-tools xz-utils unzip

On macOS, ISO tooling can be installed with:

brew install xorriso syslinux

Raw image mutation depends on guestfish. Install libguestfs through the package manager that fits your environment.

Quick Start

Create a starter config:

isocreator template create --output isocreator.yaml

Validate it:

isocreator validate isocreator.yaml

Build the image:

isocreator build --config isocreator.yaml

CLI flag based builds are advertised in the help output but are not implemented yet. Use --config for builds.

CLI Reference

isocreator <command> [options]

Command	Purpose
`build --config <file>`	Build an ISO or raw image from YAML.
`cache list`	List cached Ubuntu source images.
`cache download <version> --arch <arch>`	Download an Ubuntu image into the cache.
`cache clean`	Remove cached source images.
`template create`	Print a starter YAML config.
`template create --output <file>`	Write a starter YAML config to disk.
`validate <file>`	Load and validate a YAML config.
`version`	Print version information.
`help`	Print CLI help.

Ubuntu ISO Example

version: '1.0'

iso:
  ubuntu_version: '24.04'
  architecture: 'amd64'
  flavor: 'server'

output:
  filename: 'ubuntu-custom.iso'
  path: './output'

network:
  wifi:
    ssid: 'OfficeWiFi'
    password: 'change-me'

cloud_init:
  hostname: 'edge-node-01'
  package_update: true
  users:
    - name: 'admin'
      ssh_authorized_keys:
        - 'ssh-ed25519 AAAA...'
      sudo: 'ALL=(ALL) NOPASSWD:ALL'
      shell: '/bin/bash'
  packages:
    - docker.io
    - git
    - htop
  runcmd:
    - systemctl enable docker
    - systemctl start docker

The ISO pipeline downloads or reuses the requested Ubuntu image, extracts it with xorriso, writes NoCloud cloud-init files into nocloud/, adjusts GRUB to use that datasource, applies mutations, and repacks a bootable ISO.

Custom Source Images

Use source when you already have an image file or need a specific URL:

version: '1.0'

source:
  type: 'file'
  path: './downloads/ubuntu-24.04-live-server-amd64.iso'

iso:
  ubuntu_version: '24.04'
  architecture: 'amd64'

output:
  filename: 'custom.iso'
  path: './output'

cloud_init:
  hostname: 'custom-source-node'

URL sources are also supported:

source:
  type: 'url'
  url: 'https://example.com/base.iso'
  filename: 'base.iso'

Filesystem Mutations

Mutations run before the final artifact is written. For ISO builds, paths target the extracted ISO tree. For raw image builds, paths target the mounted boot partition.

mutations:
  - type: 'ensureDir'
    path: '/extras'
    permissions: '0755'
  - type: 'writeFile'
    path: '/extras/hello.txt'
    content: 'hello from isocreator\n'
    permissions: '0644'
  - type: 'copyFile'
    sourcePath: './files/bootstrap.sh'
    path: '/scripts/bootstrap.sh'
    permissions: '0755'

Raw Image Example

Set imageKind: raw-image or provide raw_image to use the raw image pipeline.

version: '1.0'
imageKind: 'raw-image'

source:
  type: 'url'
  url: 'https://example.com/balenaos-raspberrypi.img.xz'
  filename: 'balenaos-raspberrypi.img.xz'

raw_image:
  sourceFormat: 'auto'
  bootPartition: '/dev/sda1'
  outputCompression: 'xz'

output:
  filename: 'baseos-rpi.img.xz'
  path: './output'

network:
  wifi:
    ssid: 'FactoryWiFi'
    password: 'change-me'

cloud_init:
  hostname: 'baseos-rpi-01'
  users:
    - name: 'admin'
      ssh_authorized_keys:
        - 'ssh-ed25519 AAAA...'

balena_os:
  hostname: 'baseos-rpi-01'
  sshPublicKeys:
    - 'ssh-ed25519 AAAA...'
  configJson:
    applicationName: 'baseos'
  baseOsEnv:
    BASEOS_CLOUDLY_URL: 'https://cloudly.example.com'
    BASEOS_JOIN_TOKEN: 'replace-me'

The raw image builder resolves the source image, materializes it to a writable .img, mounts the configured boot partition with guestfish, writes generated balenaOS/BaseOS metadata, applies extra mutations, and optionally recompresses the final image with xz.

Config Reference

Field	Description
`version`	Required config schema marker.
`imageKind`	Optional build target. Use `raw-image` for raw disk images.
`source`	Optional explicit source file or URL. Required for raw image builds.
`iso`	Ubuntu ISO settings for ISO builds.
`output`	Required output filename and directory.
`network.wifi`	WiFi SSID/password used for cloud-init or NetworkManager config.
`cloud_init`	Cloud-init user-data options.
`boot_scripts`	Scripts copied into `/scripts/` in ISO builds.
`mutations`	Direct filesystem mutations.
`raw_image`	Raw source format, boot partition, and output compression options.
`balena_os`	balenaOS/BaseOS boot partition metadata.

Library Usage

The npm package is primarily a binary wrapper. For library usage, import from a source checkout or Deno-compatible source URL:

import { IsoBuilder, type IIsoConfig } from './mod.ts';

const config: IIsoConfig = {
  version: '1.0',
  iso: {
    ubuntu_version: '24.04',
    architecture: 'amd64',
  },
  output: {
    filename: 'ubuntu-custom.iso',
    path: './output',
  },
  cloud_init: {
    hostname: 'api-built-node',
  },
};

const builder = new IsoBuilder();
const result = await builder.build(config, (step, progress) => {
  console.log(`${progress}% ${step}`);
});

console.log(result.outputPath);

Use buildToOutput when the caller needs a file target or readable stream result.

Development

deno task cache
deno task check
deno task lint
deno task fmt
deno task test
deno task compile

deno task compile currently builds Linux x64, Linux ARM64, macOS x64, macOS ARM64, and Windows x64 binaries.

Source map:

Path	Purpose
`mod.ts`	CLI entry point and source exports.
`ts/cli.ts`	Command routing.
`ts/classes/iso-builder.ts`	ISO/raw pipeline selector and ISO orchestration.
`ts/classes/raw-image-builder.ts`	Raw image materialization and guestfish mutation.
`ts/classes/config-manager.ts`	YAML loading, validation, and template generation.
`ts/classes/cloud-init-generator.ts`	NoCloud cloud-init file generation.
`ts/classes/iso-source-resolver.ts`	Local/URL source resolution.
`ts/classes/iso-mutator.ts`	Direct filesystem mutation engine.
`scripts/compile-all.sh`	Multi-platform Deno compilation.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@serve.zone/isocreator