isocreator/readme.md

# isocreator

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

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

- 📡 **WiFi credentials** (via cloud-init)
- 👤 **User accounts** and SSH keys
- 📦 **Pre-installed packages**
- 🔧 **Custom boot scripts**
- ⚙️ **Full cloud-init configuration**

Perfect for:
- Raspberry Pi deployments
- Headless server installations
- Automated fleet provisioning
- Development environments

## Features

- **Multi-Platform Support**: PC (x86_64) and Raspberry Pi (ARM64)
- **Multi-Version Support**: Ubuntu 22.04 LTS, 24.04 LTS, and future versions
- **Cloud-Init Integration**: Full cloud-init user-data and network-config support
- **Caching System**: Intelligent ISO caching with multi-version support
- **Flexible Configuration**: YAML files, CLI flags, or interactive mode
- **USB Bootable**: Creates ISOs that can be written directly to USB drives

## Installation

### via npm

```bash
npm install -g @serve.zone/isocreator
```

### via Direct Script

```bash
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:**
```bash
sudo apt install xorriso syslinux-utils
```

**macOS:**
```bash
brew install xorriso syslinux
```

## Quick Start

### Interactive Mode

```bash
isocreator build
```

### Using a Config File

```bash
# 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

```bash
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

```yaml
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:

```bash
isocreator build [OPTIONS]
```

Options:
- `--config <file>` - Use a YAML config file
- `--ubuntu-version <version>` - Ubuntu version (22.04, 24.04, etc.)
- `--arch <arch>` - Architecture (amd64 or arm64)
- `--wifi-ssid <ssid>` - WiFi SSID
- `--wifi-password <password>` - WiFi password
- `--ssh-key <path>` - Path to SSH public key
- `--hostname <name>` - System hostname
- `--output <path>` - Output ISO path

### Cache Management

List cached ISOs:
```bash
isocreator cache list
```

Download an ISO to cache:
```bash
isocreator cache download 24.04 --arch amd64
```

Clean old cached ISOs:
```bash
isocreator cache clean
isocreator cache clean --older-than 6m
```

### Templates

Generate a config template:
```bash
isocreator template create
isocreator template create --output myconfig.yaml
```

### Validation

Validate a config file:
```bash
isocreator validate myconfig.yaml
```

## Use Cases

### Raspberry Pi Home Server

```yaml
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

```yaml
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:

- **Deno** - Modern TypeScript runtime
- **Cloud-init** - Industry-standard cloud instance initialization
- **xorriso** - ISO 9660 filesystem manipulation
- **Self-contained binaries** - Zero runtime dependencies

## Development

### Prerequisites

- Deno 1.40+
- xorriso
- syslinux-utils (for isohybrid)

### Setup

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

### Development Mode

```bash
deno task dev --help
```

### Testing

```bash
deno task test
```

### Build Binaries

```bash
deno task compile
```

## Contributing

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

## License

MIT License - see [license](./license) file for details

## Support

- **Issues**: https://code.foss.global/serve.zone/isocreator/issues
- **Documentation**: https://code.foss.global/serve.zone/isocreator

---

Made with ❤️ by [Lossless GmbH](https://lossless.com)