SparkOS

A revolutionary operating system that ditches Unix conventions for a modern, network-first approach. SparkOS features:

• Direct Kernel Interface: Qt6 GUI communicates directly with Linux kernel, bypassing Unix layers
• Linux Driver Layer: All hardware abstraction handled by Linux kernel drivers
• No Unix User System: No users, groups, passwords, or authentication - direct boot to GUI
• Network-First Architecture: Built around networking as the primary paradigm
• Qt6 Full-Screen GUI: Modern graphical interface from boot
• Minimal footprint: Lean system with only essential components
• Portable: dd-able disk image for USB flash drives
• Custom init: Lightweight C init system that launches GUI directly
• Immutable base: Read-only root filesystem with overlay for runtime data

Architecture

┌─────────────────────────────────────┐
│      Qt6 GUI Application            │
│   (Direct Framebuffer Rendering)    │
└─────────────────────────────────────┘
                 ↕
┌─────────────────────────────────────┐
│         Linux Kernel                │
│  • Framebuffer (/dev/fb0)           │
│  • Input devices (/dev/input/*)     │
│  • Network stack                    │
│  • All hardware drivers             │
└─────────────────────────────────────┘
                 ↕
┌─────────────────────────────────────┐
│          Hardware                   │
│  • GPU, Display, Input devices      │
│  • Network adapters                 │
│  • Storage, etc.                    │
└─────────────────────────────────────┘

Key Design Principles:

• Linux kernel provides complete hardware abstraction and driver support
• Qt6 interfaces directly with kernel through /dev, /proc, /sys interfaces
• No intermediate Unix layers (no systemd, no user management, no shells by default)
• Network-first: networking capabilities exposed directly to GUI

MVP Status

The current MVP provides:

• ✅ Custom init system written in C (no external dependencies)
• ✅ GUI-only architecture (no CLI/shell)
• ✅ dd-able AMD64 image creation scripts
• ✅ Minimal root filesystem structure
• ✅ Build system (Makefile)
• ✅ Direct network initialization via C ioctl
• ✅ DNS configuration with public fallback servers
• ✅ Docker container for testing
• ✅ Automated builds and publishing to GHCR
• ✅ Multi-architecture Docker images (AMD64 and ARM64)
• ✅ CI/CD pipeline for compiled release packages
• ✅ GitHub releases with pre-built binaries

Prerequisites

To build SparkOS, you need:

• GCC compiler
• GNU Make
• Linux system (for building)

To create bootable images (optional):

• Root privileges
• syslinux bootloader
• parted partitioning tool
• losetup for loop devices
• mkfs.ext4 filesystem tools

Quick Start

Using UEFI-Bootable Disk Image (Recommended - Boot from USB)

Download the UEFI-bootable image from the GitHub Releases page:

# 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:

1. Insert the USB drive into a UEFI-capable system
2. Enter BIOS/UEFI settings (usually F2, F12, DEL, or ESC at boot)
3. Select the USB drive as boot device
4. 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 (completely self-contained, no external dependencies)
• ✅ Ready to boot - Direct to Qt6 GUI, no CLI

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
• No CLI tools: Pure GUI-only architecture
• Multi-architecture support: Available for both AMD64 (x86_64) and ARM64 (aarch64) architectures

When you run the Docker image, it automatically verifies:

• Custom init system binary (statically linked, no dependencies)
• Root filesystem structure

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 (no external dependencies)

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) via direct system calls
• Initializes network interfaces via direct C ioctl calls
• Spawns Qt6 GUI application directly
• Handles process reaping
• Respawns GUI on exit
• No external dependencies: Completely self-contained

Root Filesystem

Minimal filesystem structure for GUI-only OS:

• /sbin: Init binary only
• /etc: Minimal system configuration
• /proc, /sys, /dev: Kernel interfaces
• /tmp: Temporary files
• /usr: Qt6 GUI application and libraries
• /var: Variable data (overlay mount)
• /root: Root home

Networking

SparkOS provides network initialization through direct C code:

• Interface Management: Direct ioctl calls to bring up network interfaces
• DNS: Fallback to public DNS servers (8.8.8.8, 8.8.4.4, 1.1.1.1, 1.0.0.1)
• DHCP: Managed by Qt6 NetworkManager in GUI
• WiFi: Configured through Qt6 GUI

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:

1. Commit and push your changes to the main branch
2. Create and push a version tag:

   git tag v1.0.0
   git push origin v1.0.0
   

3. 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:

1. Go to https://github.com/johndoe6345789/SparkOS/releases/new
2. Choose or create a tag (e.g., v1.0.0)
3. Fill in the release title and description
4. Upload the sparkos-release.zip (built locally with docker-release.sh)
5. 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 Components to Root Filesystem

To create a fully functional bootable system:

# Required components:
# 1. Qt6 GUI application - Build with make gui
# 2. Qt6 libraries - Copy Qt6 runtime libraries to rootfs/usr/lib
# 3. Linux kernel - Include kernel binary for bootloader

# Qt6 GUI is built and installed via:
make gui
make install  # Installs to rootfs/usr/bin/sparkos-gui

# Note: Qt6 must be compiled with linuxfb support for framebuffer rendering

Future Roadmap

• Qt6/QML full screen GUI implementation
• Wayland compositor integration
• Network management via Qt6 NetworkManager
• WiFi configuration through GUI
• Advanced network configuration UI
• System settings and configuration UI

Contributing

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

1. Maintaining minimal footprint
2. Clean, readable code
3. Proper documentation
4. GUI-only architecture (no CLI/shell)

License

See LICENSE file for details.

Notes

This is an MVP implementation. The system currently provides:

• Custom init system with direct network initialization
• GUI-only architecture (no CLI/shell)
• Build infrastructure
• Image creation tooling
• Self-contained init with no external dependencies

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

• Linux kernel binary (vmlinuz) with framebuffer and networking support
• Qt6 GUI application (sparkos-gui)
• Qt6 runtime libraries
• Bootloader installation (handled by scripts)

Minimum System Requirements:

• Kernel: Linux kernel with framebuffer and networking support
• Init: Custom SparkOS init (included, no dependencies)
• GUI: Qt6 application with linuxfb platform support
• Libraries: Qt6 runtime libraries for GUI

System Philosophy:

• No CLI tools: Everything through Qt6 GUI
• No shell: Direct kernel-to-GUI communication
• No busybox: Self-contained init system
• Network-first: Networking integrated into GUI