# Download the disk image (replace VERSION with actual version, e.g., v1.0.0)
wget https://github.com/johndoe6345789/SparkOS/releases/download/VERSION/sparkos.img.gz

# Decompress the image
gunzip sparkos.img.gz

# Write to USB drive (Linux - BE CAREFUL!)
sudo dd if=sparkos.img of=/dev/sdX bs=4M status=progress oflag=sync

⚠️ WARNING: Replace /dev/sdX with your actual USB device (e.g., /dev/sdb). This will DESTROY ALL DATA on the target drive!

Boot Instructions:

Insert the USB drive into a UEFI-capable system
Enter BIOS/UEFI settings (usually F2, F12, DEL, or ESC at boot)
Select the USB drive as boot device
SparkOS will boot automatically

The UEFI-bootable disk image includes:

✅ UEFI boot support with GRUB bootloader
✅ GPT partition table with ESP (EFI System Partition)
✅ Linux kernel ready to boot
✅ SparkOS init system and busybox utilities
✅ Ready to boot - No additional setup required

Using Pre-built Binary Package

Download the binary package from the GitHub Releases page:

# Download the latest release (replace VERSION with actual version, e.g., v1.0.0)
wget https://github.com/johndoe6345789/SparkOS/releases/download/VERSION/sparkos-release.zip

# Extract the package
unzip sparkos-release.zip
cd sparkos/

# The init binary is already compiled and ready to use
ls -lh init

# Copy to your rootfs or use directly
cp init /path/to/your/rootfs/sbin/init

The release package includes:

Pre-compiled init binary (statically linked, ready to use)
Complete source code
Build scripts and configuration
Root filesystem structure
Full documentation

Using Docker (Recommended for Testing)

The easiest way to test SparkOS is using the pre-built Docker image from GitHub Container Registry:

# Pull and run the latest image (automatically selects the correct architecture)
docker pull ghcr.io/johndoe6345789/sparkos:latest
docker run --rm ghcr.io/johndoe6345789/sparkos:latest

# Or build locally
docker build -t sparkos:local .
docker run --rm sparkos:local

# Or use Docker Compose for even simpler testing
docker-compose up

# Build for specific architecture
docker buildx build --platform linux/amd64 -t sparkos:amd64 --load .
docker buildx build --platform linux/arm64 -t sparkos:arm64 --load .

The Docker image includes:

Pre-built init system binary
Minimal root filesystem structure
Test environment for validation
BusyBox shell and utilities: Alpine Linux base provides BusyBox (verified on startup)
Multi-architecture support: Available for both AMD64 (x86_64) and ARM64 (aarch64) architectures

When you run the Docker image, it automatically verifies:

BusyBox version and installation
Available BusyBox applets (sh, ls, cat, etc.)
Required networking tools (udhcpc, ip, ping, wget)
Custom init system binary

Images are automatically built and published to GitHub Container Registry on every push to main branch.

Building Releases with Docker (No Root Required):

Create release packages easily using Docker without needing root privileges or special tools:

# Build a release package for version v1.0.0
./scripts/docker-release.sh v1.0.0

# The release ZIP will be created in release/sparkos-release.zip
# This is the same artifact that GitHub Actions creates

Building the Init System

# Build the init binary
make init

# Or use the quick build script
./scripts/build.sh

Setting Up Root Filesystem

# Create the root filesystem structure
./scripts/setup_rootfs.sh

# Install init to rootfs
make install

Creating a UEFI-Bootable Image

Using Docker (Recommended - No Root Required):

Build UEFI-bootable disk images easily using Docker without needing root privileges on your host:

# Build the UEFI-bootable disk image using Docker
make image-docker

# Or use the script directly
./scripts/build-image.sh

# The compressed UEFI-bootable image will be in release/sparkos.img.gz

This creates a complete UEFI-bootable image with:

GPT partition table
EFI System Partition (ESP) with FAT32
GRUB UEFI bootloader
Linux kernel
SparkOS init system and busybox

Traditional Method (Requires Root):

⚠️ Warning: This method is for creating custom partitioned images and requires root privileges.

# Install required tools (Ubuntu/Debian)
sudo apt-get install syslinux parted

# Build everything and create image
make all
sudo make image

Installing to USB Drive

Once you have created the sparkos.img file, use the installation script to write it to a USB drive or storage device:

# Use the installation script (RECOMMENDED)
sudo ./scripts/install.sh /dev/sdX

# The script will:
# - Validate the target drive
# - Display warnings about data destruction
# - Require confirmation before proceeding
# - Show progress during installation
# - Verify successful installation

Replace /dev/sdX with your actual USB device (e.g., /dev/sdb, /dev/nvme1n1).

⚠️ WARNING: This will permanently erase all data on the target drive!

Project Structure

SparkOS/
├── .github/             # GitHub Actions workflows
│   └── workflows/
│       └── docker-publish.yml  # Docker build and publish workflow
├── config/              # Build configuration files
│   └── build.conf       # Build parameters
├── scripts/             # Build and setup scripts
│   ├── build.sh         # Quick build script
│   ├── setup_rootfs.sh  # Root filesystem setup
│   ├── create_image.sh  # Image creation script
│   └── install.sh       # Installation script for USB drives
├── src/                 # Source code
│   └── init.c           # Custom init system
├── rootfs/              # Root filesystem (generated)
│   ├── bin/             # Essential binaries
│   ├── sbin/            # System binaries
│   ├── etc/             # Configuration files
│   └── ...              # Standard FHS directories
├── Dockerfile           # Docker image definition
├── Makefile             # Build system
└── README.md            # This file

Architecture

Init System

SparkOS uses a custom init system (/sbin/init) that:

Mounts essential filesystems (proc, sys, dev, tmp)
Initializes wired networking via DHCP
Spawns a busybox sh login shell
Handles process reaping
Respawns shell on exit

Root Filesystem

Follows the Filesystem Hierarchy Standard (FHS):

/bin, /sbin: Essential binaries
/etc: System configuration
/proc, /sys, /dev: Kernel interfaces
/tmp: Temporary files
/usr: User programs and libraries
/var: Variable data
/root: Root user home
/home: User home directories

Networking

SparkOS provides wired networking for initial bootstrap:

DHCP: Automatic IP configuration via busybox udhcpc
DNS: Fallback to public DNS servers (8.8.8.8, 8.8.4.4, 1.1.1.1, 1.0.0.1)
Interface: Primary wired interface (eth0) configured automatically
WiFi: Will be configured later via spark CLI after installation

Development

CI/CD and Docker

SparkOS uses GitHub Actions for continuous integration and delivery:

Automated Builds:

Docker images are automatically built on every push to main/develop branches
Compiled release packages are automatically built on every push to main/develop branches
Both are also built for pull requests (testing only, not published)
Tagged releases automatically create versioned Docker images and GitHub releases with compiled binaries
Multi-architecture builds: Images are built for both AMD64 (x86_64) and ARM64 (aarch64)

Compiled Releases:

Pre-compiled init binaries are available as GitHub releases for version tags
Release packages include: compiled init binary, source code, build scripts, and documentation
Download releases from the GitHub Releases page
Build artifacts are available for all workflow runs (retained for 90 days)

Container Registry:

Images are published to GitHub Container Registry (GHCR)
Pull images: docker pull ghcr.io/johndoe6345789/sparkos:latest
Available tags: latest, main, develop, version tags (e.g., v1.0.0)
Docker will automatically select the correct architecture for your platform

Docker Development:

# Build Docker image locally
docker build -t sparkos:dev .

# Build for multiple architectures (requires Docker Buildx)
docker buildx build --platform linux/amd64,linux/arm64 -t sparkos:multiarch .

# Test the image
docker run --rm sparkos:dev

# Or use Docker Compose
docker-compose up

# Inspect the init binary
docker run --rm sparkos:dev sh -c "ls -lh /sparkos/rootfs/sbin/init"

Creating Releases

Using Docker (Recommended - No Root Required):

Build release packages locally using Docker without needing root privileges:

# Build a release package
./scripts/docker-release.sh v1.0.0

# The release ZIP will be in release/sparkos-release.zip
# This is identical to what GitHub Actions creates

Creating a GitHub Release:

Commit and push your changes to the main branch
Create and push a version tag:
```
git tag v1.0.0
git push origin v1.0.0
```
GitHub Actions will automatically:
- Build the init binary
- Create the release package ZIP
- Build and publish Docker images (AMD64 + ARM64)
- Create a GitHub Release with the artifacts
- Publish to GitHub Container Registry

The release will be available at:

GitHub Releases: https://github.com/johndoe6345789/SparkOS/releases
Docker Images: ghcr.io/johndoe6345789/sparkos:v1.0.0

Manual Release Creation:

You can also create a release manually:

Go to https://github.com/johndoe6345789/SparkOS/releases/new
Choose or create a tag (e.g., v1.0.0)
Fill in the release title and description
Upload the sparkos-release.zip (built locally with docker-release.sh)
Publish the release

For detailed instructions on creating releases, see RELEASING.md.

Building Components

# Build init system only
make init

# Build release package using Docker
make docker-release

# Install to rootfs
make install

# Clean build artifacts
make clean

# Show help
make help

Adding Binaries to Root Filesystem

To create a fully functional system, you need to populate the rootfs with binaries:

# Required binaries (statically linked recommended)
# 1. Busybox - provides shell and most utilities including networking
cp /path/to/busybox rootfs/bin/

# 2. Git - for cloning spark CLI
cp /path/to/git rootfs/bin/
# Note: If git is dynamically linked, you'll need to copy its libraries too

# 3. Sudo - for privilege elevation
cp /path/to/sudo rootfs/bin/

# Create busybox symlinks for common utilities
cd rootfs/bin
for cmd in sh ls cat mkdir rm cp mount umount chmod chown ln \
           ip ifconfig ping wget udhcpc; do
    ln -sf busybox $cmd
done
cd ../..

# If using dynamically linked binaries, copy required libraries
ldd rootfs/bin/busybox  # Check dependencies
ldd rootfs/bin/git      # Check dependencies
ldd rootfs/bin/sudo     # Check dependencies
# Copy libraries to rootfs/lib or rootfs/lib64 as needed

Testing Network Connectivity

Once booted, you can test the network:

# Check interface status
ip addr show

# Test DNS resolution
ping -c 3 google.com

# Test direct IP connectivity
ping -c 3 8.8.8.8

# Download a file
wget http://example.com/file

Future Roadmap

Qt6/QML full screen GUI
Wayland compositor integration
C++ CLI tools (spark command)
Package management via spark CLI
WiFi configuration via spark CLI
Advanced network configuration

Contributing

Contributions are welcome! This is an early-stage project focused on:

Maintaining minimal footprint
Clean, readable code
Proper documentation

License

See LICENSE file for details.

Notes

This is an MVP implementation. The system currently provides:

Basic init system with network initialization
Shell environment
Build infrastructure
Image creation tooling
Wired networking configuration

To create a fully bootable system, you'll also need:

Linux kernel binary (vmlinuz)
Essential system binaries: busybox, git, sudo
Required libraries (if using dynamically linked binaries)
Bootloader installation (handled by scripts)

Minimum System Requirements:

Kernel: Linux kernel with networking support
Init: Custom SparkOS init (included)
Shell: Busybox with networking utilities (udhcpc, ip/ifconfig, ping, wget)
VCS: Git (for installing spark CLI)
Security: Sudo (for privilege elevation)

After bootstrap:

Use wired network to clone spark CLI via git
Use spark CLI to configure WiFi and other system features
Install additional packages as needed via spark CLI

Languages

Shell 66.7%

C 13.8%

C++ 11.3%

Makefile 4.3%

Dockerfile 2.3%

Other 1.6%