feat(core): Initial project scaffold and implementation: Deno CLI, ISO tooling, cloud-init generation, packaging and installer scripts
This commit is contained in:
312
readme.md
Normal file
312
readme.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# isocreator
|
||||
|
||||
> Ubuntu ISO customization tool for PC and Raspberry Pi with WiFi and cloud-init configuration
|
||||
|
||||
[](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)
|
||||
Reference in New Issue
Block a user