@serve.zone/isocreator

a tool to create isos for managed edge devices

readme.md for @serve.zone/isocreator

Ubuntu ISO customization tool for PC and Raspberry Pi with WiFi and cloud-init configuration

License: MIT

Overview

isocreator is a command-line tool that creates customized Ubuntu Server ISOs with pre-configured:

Perfect for:

Features

Installation

via npm

npm install -g @serve.zone/isocreator

via Direct Script

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

System Dependencies

isocreator requires the following tools to be installed:

Ubuntu/Debian:

sudo apt install xorriso syslinux-utils

macOS:

brew install xorriso syslinux

Quick Start

Interactive Mode

isocreator build

Using a Config File

# Generate a template
isocreator template create --output myconfig.yaml

# Edit the config file
nano myconfig.yaml

# Build the ISO
isocreator build --config myconfig.yaml

Using CLI Flags

isocreator build \
  --ubuntu-version 24.04 \
  --arch amd64 \
  --wifi-ssid "MyWiFi" \
  --wifi-password "secret123" \
  --ssh-key ~/.ssh/id_rsa.pub \
  --hostname "myserver" \
  --output ./custom-ubuntu.iso

Configuration

Example Config File

version: "1.0"

# Base ISO settings
iso:
  ubuntu_version: "24.04"
  architecture: "amd64"  # or arm64 for Raspberry Pi

# Output settings
output:
  filename: "ubuntu-custom.iso"
  path: "./output"

# WiFi configuration (via cloud-init)
network:
  wifi:
    ssid: "MyWiFi"
    password: "secret123"

# Cloud-init configuration
cloud_init:
  hostname: "myserver"

  # User accounts
  users:
    - name: "admin"
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3NzaC1yc2E..."
      sudo: "ALL=(ALL) NOPASSWD:ALL"
      shell: "/bin/bash"

  # Packages to install on first boot
  packages:
    - docker.io
    - git
    - htop

  # Commands to run on first boot
  runcmd:
    - systemctl enable docker
    - systemctl start docker
    - echo "Setup complete!"

# Custom boot scripts
boot_scripts:
  - name: "setup-docker"
    path: "./scripts/setup-docker.sh"

Commands

Build

Build a customized ISO:

isocreator build [OPTIONS]

Options:

Cache Management

List cached ISOs:

isocreator cache list

Download an ISO to cache:

isocreator cache download 24.04 --arch amd64

Clean old cached ISOs:

isocreator cache clean
isocreator cache clean --older-than 6m

Templates

Generate a config template:

isocreator template create
isocreator template create --output myconfig.yaml

Validation

Validate a config file:

isocreator validate myconfig.yaml

Use Cases

Raspberry Pi Home Server

iso:
  ubuntu_version: "24.04"
  architecture: "arm64"

network:
  wifi:
    ssid: "HomeNetwork"
    password: "homepass123"

cloud_init:
  hostname: "pi-server"
  users:
    - name: "pi"
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3..."
      sudo: "ALL=(ALL) NOPASSWD:ALL"

  packages:
    - docker.io
    - docker-compose

  runcmd:
    - systemctl enable docker

Headless Development Server

iso:
  ubuntu_version: "24.04"
  architecture: "amd64"

cloud_init:
  hostname: "devbox"

  users:
    - name: "developer"
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3..."
      sudo: "ALL=(ALL) NOPASSWD:ALL"

  packages:
    - build-essential
    - git
    - docker.io
    - nodejs
    - npm

Architecture

isocreator is built with:

Development

Prerequisites

Setup

git clone https://code.foss.global/serve.zone/isocreator.git
cd isocreator
deno task cache

Development Mode

deno task dev --help

Testing

deno task test

Build Binaries

deno task compile

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - see license file for details

Support

Made with ❤️ by Lossless GmbH

changelog.md for @serve.zone/isocreator

2025-10-24 - 1.2.3 - fix(deps)

Update Deno dependencies and configuration, commit lockfile, and adjust plugins exports

2025-10-24 - 1.2.2 - fix(logging)

Refactor logging and plugin imports: remove push.rocks dependencies and provide a simple console-based logger with a compatibility shim

2025-10-24 - 1.2.1 - fix(deno)

Set Deno nodeModulesDir to 'auto' and add local .claude settings

2025-10-24 - 1.2.0 - feat(ci)

Improve release workflow: compile multi-platform binaries, generate checksums, create Gitea release and upload assets, and add local settings

2025-10-24 - 1.1.0 - feat(core)

Initial project scaffold and implementation: Deno CLI, ISO tooling, cloud-init generation, packaging and installer scripts

All notable changes to isocreator will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

[1.0.0] - TBD

Added