container-host

A simplified Go-based tool for creating and managing Fedora CoreOS virtual machines with Docker and Kubernetes support using QEMU. Features single-port access with subdomain-based routing.

Quick Start

Install and run container-host using your preferred Node package manager:

# Using npm
npx container-host-cli [options]

# Using yarn
yarn dlx container-host-cli [options]

# Using pnpm
pnpm dlx container-host-cli [options]

# Using bun
bunx container-host-cli [options]

# Or install globally
npm install -g container-host-cli
container-host [options]

The CLI automatically downloads the appropriate binary for your platform and architecture.

Overview

container-host automates the setup of Fedora CoreOS VMs with pre-configured Docker Engine and Kubernetes (K0s) support. It handles VM image downloads, SSH key generation, Ignition configuration, and multi-instance deployments across different architectures.

Features

• Single-port architecture: Access all services through one port with subdomain routing
• Multi-architecture support: x86_64, aarch64, and other QEMU-supported architectures
• Automated VM provisioning: Downloads CoreOS images and configures VMs automatically
• Docker integration: Pre-configured Docker Engine with API access via Caddy proxy
• Kubernetes ready: K0s integration with API endpoints via reverse proxy
• Multi-instance deployment: Run multiple VM instances with incremented ports
• Cross-platform: Works on macOS (HVF), Linux (KVM), and Windows (WHPX)
• SSH key management: Automatic SSH key pair generation and deployment
• Ignition configuration: Automated CoreOS Ignition config with reverse proxy setup
• Configurable CoreOS source: Use custom CoreOS image download URLs

Prerequisites

• Go: Version 1.24 or later
• QEMU: System-appropriate QEMU installation
  • macOS: brew install qemu
  • Ubuntu/Debian: apt install qemu-system
  • Windows: Install QEMU from official website
• Hardware acceleration (recommended):
  • macOS: Hypervisor Framework (built-in)
  • Linux: KVM support
  • Windows: Hyper-V or WHPX

Installation (Repository)

git clone https://github.com/geoffsee/container-host.git
cd container-host
make build

Configuration

Copy container-host.config.json to customize a deployment:

Example

{
  "vm": {
    "architecture": "aarch64",
    "version": "42.20250803.3.0",
    "memory": "4096",
    "cpus": "4",
    "instances": 1
  },
  "network": {
    "proxyPort": "3737",
    "hostname": "localhost"
  },
  "ssh": {
    "publicKeyPath": "ssh_keys/coreos_rsa.pub",
    "privateKeyPath": "ssh_keys/coreos_rsa"
  },
  "coreOS": {
    "baseUrl": "https://builds.coreos.fedoraproject.org"
  },
  "qemu": {
    "enableAcceleration": true,
    "customArgs": []
  },
  "debug": {
    "printIgnitionConfig": true,
    "verbose": false
  }
}

Configuration Options

| Section | Field | Default | Description | |---------|-------|---------|-------------| | vm | architecture | aarch64 | Target architecture (aarch64, x86_64) | | vm | version | 42.20250803.3.0 | Fedora CoreOS version | | vm | memory | 4096 | RAM in MB per instance | | vm | cpus | 4 | CPU count per instance | | vm | instances | 1 | Number of VM instances to create | | network | proxyPort | 3737 | Single proxy port for subdomain routing | | network | hostname | localhost | Base hostname for subdomain routing | | ssh | publicKeyPath | ssh_keys/coreos_rsa.pub | Path to SSH public key | | ssh | privateKeyPath | ssh_keys/coreos_rsa | Path to SSH private key | | coreOS | baseUrl | https://builds.coreos.fedoraproject.org | CoreOS image download URL | | qemu | enableAcceleration | true | Use hardware acceleration | | qemu | customArgs | [] | Additional QEMU arguments | | debug | printIgnitionConfig | true | Print generated Ignition config | | debug | verbose | false | Enable verbose logging |

Usage

Basic Usage

Start a single VM with default configuration:

make run

Custom Architecture and Version

./container-host -arch x86_64 -version 41.20240101.1.0

Connect to Your VM

Once started, the VM provides several connection methods:

# SSH access (direct)
ssh -i ssh_keys/coreos_rsa -p 2222 core@localhost

# Single-port subdomain access (configure your /etc/hosts or use a proper DNS setup)
# Add to /etc/hosts:
# 127.0.0.1 docker.localhost k8s.localhost vnc.localhost ssh.localhost

# Docker API access via subdomain
curl http://docker.localhost:3737/version

# Kubernetes API via subdomain
curl http://k8s.localhost:3737/

# Or access services directly via localhost with configured hostname
curl http://localhost:3737/        # Default web interface

Multiple Instances

Configure multiple instances in container-host.config.json:

{
  "vm": {
    "instances": 3
  }
}

This creates 3 VMs with incremented ports:

• Instance 1: SSH 2222, Proxy 3737
• Instance 2: SSH 2223, Proxy 3738
• Instance 3: SSH 2224, Proxy 3739

Each instance runs its own Caddy reverse proxy for subdomain routing.

Directory Structure

container-host/
├── configs/           # Ignition configurations
├── images/           # Downloaded CoreOS images
├── ssh_keys/         # Generated SSH key pairs
├── main.go           # Main application
├── coreos_download.go # Image download logic
└── container-host.config.json # Configuration file

Architecture Support

The tool automatically detects and configures QEMU for your target architecture:

• aarch64: Uses qemu-system-aarch64 with ARM64 EFI firmware
• x86_64: Uses qemu-system-x86_64 with OVMF firmware
• Custom: Supports any QEMU-compatible architecture

Networking

Single-Port Architecture

Each VM instance uses a single proxy port (default: 3737) with Caddy reverse proxy for subdomain-based routing:

| Access Method | URL Pattern | Purpose | |---------------|------------|---------| | SSH | localhost:2222+ | Direct SSH access | | Docker API | docker.hostname:proxyPort | Docker API via subdomain | | Kubernetes API | k8s.hostname:proxyPort | K8s API via subdomain | | K0s API | k0s.hostname:proxyPort | K0s management via subdomain | | VNC Web | vnc.hostname:proxyPort | VNC web client via subdomain | | SSH Web | ssh.hostname:proxyPort | SSH web terminal via subdomain | | Default Web | hostname:proxyPort | Default web interface |

Multiple Instances

For multiple instances, ports are incremented:

• Instance 1: SSH 2222, Proxy 3737
• Instance 2: SSH 2223, Proxy 3738
• Instance 3: SSH 2224, Proxy 3739

Development

Building from Source

go build -o container-host *.go

Cleaning Up

# Remove binary
make clean

# Reset VMs and SSH keys
make clean_vm

Troubleshooting

Common Issues

QEMU binary not found

• Ensure QEMU is installed and in PATH
• Check architecture-specific binary names

Permission denied on SSH keys

• SSH keys are auto-generated with correct permissions
• Check ssh_keys/ directory exists

VM fails to start

• Verify hardware acceleration is available
• Check QEMU logs for detailed errors
• Try disabling acceleration in config

Docker connection refused

• Wait for VM to fully boot (30-60 seconds)
• Verify Docker service is running: ssh -p 2222 core@localhost 'sudo systemctl status docker'

Debug Mode

Enable verbose logging:

{
  "debug": {
    "printIgnitionConfig": true,
    "verbose": true
  }
}

Related Documentation

• KUBERNETES.md - Kubernetes cluster setup guide
• Fedora CoreOS Documentation
• Ignition Configuration

System-Level Operations Warning

This tool performs system-level operations that may:

• Consume significant system resources (CPU, memory, disk space, network bandwidth)
• Modify network configurations and create network interfaces
• Create and manage virtual machine processes with elevated privileges
• Download and execute third-party software (CoreOS images, containers)
• Manage SSH keys and cryptographic materials
• Expose network services on your system

Users are responsible for:

• Understanding the security implications of running virtual machines
• Implementing appropriate network security measures
• Monitoring resource usage and system impact
• Ensuring compliance with organizational security policies
• Securing SSH keys and access credentials

Third-Party Dependencies

This tool relies on external dependencies and services:

• Fedora CoreOS Images: Downloaded from official Fedora servers
• QEMU: System virtualization software
• Docker: Container runtime and API
• Kubernetes (K0s): Container orchestration platform

Users should review the security and licensing terms of these dependencies independently.

Export Control Compliance

This software may be subject to export control regulations. Users are responsible for ensuring compliance with applicable export control laws in their jurisdiction.

Data Privacy

Virtual machines created by this tool may process, store, or transmit sensitive data. Users are responsible for:

• Implementing appropriate data protection measures
• Ensuring compliance with privacy regulations (GDPR, CCPA, etc.)
• Securing VM instances and their data
• Managing data retention and deletion

Creating Bootable Hardware ISO (experimental)

The tool now supports creating bootable ISO images for hardware deployment using the Fedora CoreOS live approach with embedded Ignition configuration.

ISO Generation Mode

Generate a bootable ISO with embedded configuration:

./container-host --iso --arch aarch64 --version 42.20250901.3.0 --iso-output my-hardware-setup.iso

This creates an ISO that:

• Downloads the latest CoreOS live ISO using coreos-installer
• Embeds your Ignition configuration with SSH keys and Docker setup
• Enables coreos.liveiso.fromram for running entirely from RAM
• Includes all your customizations (SSH keys, Docker configuration, etc.)

Features of Generated ISOs

The generated bootable ISOs include:

• RAM-only operation: Runs entirely from RAM using coreos.liveiso.fromram
• Embedded Ignition config: No need for separate configuration files
• Pre-configured SSH access: Your SSH keys are embedded
• Docker engine setup: Automatically configured and started
• Network services: All configured ports and services ready

Writing ISO to USB/DVD

Write the generated ISO to bootable media:

# Linux/macOS (requires sudo)
sudo go run isowrite.go -iso my-hardware-setup.iso -device /dev/sdX -verify

# macOS tip: use the raw node for speed (e.g., /dev/rdisk3)
sudo go run isowrite.go -iso my-hardware-setup.iso -device /dev/rdisk3 -verify

# Windows (run in elevated shell)
go run isowrite.go -iso C:\my-hardware-setup.iso -device \\.\PhysicalDrive2 -verify

# Alternative: use dd command
dd if=my-hardware-setup.iso of=/dev/sdX bs=4M status=progress oflag=sync

Tips per OS

• Linux

  • Find your USB device: lsblk -o NAME,SIZE,TYPE,MOUNTPOINT
  • Unmount any mounted partitions on that device before writing: sudo umount /dev/sdX*
  • Prefer the whole-disk node (e.g., /dev/sdX, not a partition like /dev/sdX1).

• macOS

  • List disks: diskutil list
  • Unmount the whole device: diskutil unmountDisk /dev/diskN
  • Use the raw node for speed: /dev/rdiskN

• Windows

  • List physical drives in Disk Management or Get-Disk in PowerShell.
  • Make sure no partitions on the USB are mounted (right-click → “Offline” or remove drive letters).
  • Device path format: \\.\PhysicalDriveN

Contributing

Please read CONTRIBUTING.md for detailed guidelines on:

• Code of conduct and community standards
• Development setup and processes
• Legal requirements for contributors
• Security considerations for contributions
• Testing and documentation requirements

Security Issues

If you discover security vulnerabilities, please report them responsibly: Security Policy. Do not report security issues through public GitHub issues.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Geoff Seemueller

The MIT License is a permissive license that allows commercial and private use, modification, and distribution. However, it provides no warranty and limits liability. See the full license text for complete terms.

Legal Notice and Disclaimers

Limitation of Liability

IMPORTANT: container-host-cli manages system-level resources including virtual machines, network interfaces, and processes. Use at your own risk.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

graph TB
    CLI[container-host CLI] --> Config[container-host.config.json]
    CLI --> Download[CoreOS Image Download]
    CLI --> SSH[SSH Key Generation]
    CLI --> Ignition[Ignition Config Generation]

    Download --> Images[images/ Directory]
    SSH --> Keys[ssh_keys/ Directory]
    Ignition --> Configs[configs/ Directory]

    CLI --> QEMU[QEMU VM Management]
    QEMU --> VM1[VM Instance 1]
    QEMU --> VM2[VM Instance 2]
    QEMU --> VMN[VM Instance N]

    VM1 --> CoreOS1[Fedora CoreOS + Caddy Proxy]
    VM2 --> CoreOS2[Fedora CoreOS + Caddy Proxy]
    VMN --> CoreOSN[Fedora CoreOS + Caddy Proxy]

    CoreOS1 --> Docker1[Docker Engine]
    CoreOS1 --> K8s1[K0s/Kubernetes]
    CoreOS1 --> Caddy1[Caddy Reverse Proxy]
    CoreOS2 --> Docker2[Docker Engine]
    CoreOS2 --> K8s2[K0s/Kubernetes]
    CoreOS2 --> Caddy2[Caddy Reverse Proxy]
    CoreOSN --> DockerN[Docker Engine]
    CoreOSN --> K8sN[K0s/Kubernetes]
    CoreOSN --> CaddyN[Caddy Reverse Proxy]

    VM1 --> Ports1[SSH:2222, Proxy:3737]
    VM2 --> Ports2[SSH:2223, Proxy:3738]
    VMN --> PortsN[SSH:222N, Proxy:373N]

    Host[Host System] --> HW[Hardware Acceleration<br/>HVF/KVM/WHPX]
    QEMU --> HW

    User[User] --> Host
    User -.->|SSH| Ports1
    User -.->|docker.localhost:3737| Caddy1
    User -.->|k8s.localhost:3737| Caddy1
    User -.->|vnc.localhost:3737| Caddy1

How It Works

flowchart TD
    Start([User runs container-host]) --> Config{Config exists?}
    Config -->|No| Default[Use default config]
    Config -->|Yes| Load[Load config file]

    Default --> Setup[Setup Phase]
    Load --> Setup

    Setup --> Download[Download Fedora CoreOS image]
    Setup --> Keys[Generate SSH key pair]
    Setup --> Ignition[Create Ignition config with Caddy]

    Download --> Launch[Launch QEMU VMs]
    Keys --> Launch
    Ignition --> Launch

    Launch --> Boot[VMs boot with CoreOS]
    Boot --> Services[Start Docker + Caddy Proxy]
    Services --> Ready[✅ Ready for use]

    Ready --> SSH[SSH: localhost:2222+]
    Ready --> Proxy[Single Port: localhost:3737+]

    Proxy --> Docker[docker.hostname → Docker API]
    Proxy --> K8s[k8s.hostname → K8s API]
    Proxy --> VNC[vnc.hostname → VNC Web]
    Proxy --> Web[hostname → Default Web]