🖥

GingerOS

v1.0.0 · August 1, 2026

// A Linux distro built from source.

GingerOS is a custom Linux distribution built entirely from scratch using Linux From Scratch (LFS). Engineered for performance, transparency, and full control over every layer of the stack.

Download Latest View on GitHub

// features

Built from Linux From Scratch

Custom build orchestration system

Minimal footprint, maximum control

Bootable ISO with installer

Fully open source

// usage

bash

# Install GingerOS
sudo ./installer.sh --disk /dev/sda

// release_notes — v1.0.0

# GingerOS v1.0.0-stable

**Release date**: 2026-08-01
**Codename**: stable

GingerOS is a complete Linux distribution built from source following the
Linux From Scratch 13.0 (systemd edition) book, packaged as a bootable
installer ISO and verified to install and boot cleanly end-to-end.

## Highlights

- **From-scratch LFS 13.0 system** — nothing copied from a host distro.
- **Bootable installer ISO** (`gingeros-installer.iso`) with a single static
  Go installer binary — no Python/runtime dependencies on the ISO or target.
- **systemd-based runtime**: networkd (DHCP), logind, journald, dbus all
  `active` on a fresh install.
- **Zero-host-pollution build**: all LFS work happens inside an isolated
  QEMU disk image; the host only needs QEMU, debootstrap, and Python/Go tools.
- **Two control surfaces**: Go HUD terminal client and React web dashboard
  (FastAPI backend on `:8087`).

## Included software

| Component | Version |
|-----------|---------|
| LFS base | 13.0 (systemd edition) |
| Linux kernel | 6.18.10 (`x86_64-lfs-linux-gnu`) |
| glibc | 2.43 |
| GCC | 15.2.0 |
| Binutils | 2.46.0 |
| systemd | 259 |
| Init system | systemd (networkd / logind / journald / dbus) |
| Target | x86_64, merged-`/usr` layout |

## Installer (on the ISO)

The Go installer (`lfs/iso/installer/main.go`) performs 5 steps:

1. **Partitioning** — target wipe, GPT table, ext4 root partition.
2. **Extract Filesystem** — streaming extraction of the purged rootfs.
3. **Hardware Sync** — kernel install, merged-`/usr` symlinks, and rewriting
   `/etc/fstab` with the target's real root UUID.
4. **User Setup** — user account creation and password setup.
5. **Bootloader** — GRUB installation, hostname, and network config.

The installed system boots directly to a login prompt on both VGA and the
serial console (`console=ttyS0`).

## Verification

Tested headlessly in QEMU/KVM on a fresh 20 GB disk:

- Full install completes (all 5 steps, exit 0).
- System boots to `gingeros login:` on `ttyS0`.
- `ginger` account logs in; `root` password works via `su`.
- `systemctl is-system-running` → **running** (not degraded).
- `systemd-networkd` `active (running)` with DHCP `10.0.2.15/24`.
- `systemd-logind` and `dbus` `active (running)`.
- eth0 `UP`, DHCP lease acquired.

## Bug fixes in this release

- **Installer fstab UUID**: the installed `/etc/fstab` now uses the target
  partition's real UUID (was the build disk's UUID), fixing a first-boot
  `systemd-remount-fs.service` failure and `degraded` state.
- **LFS systemd users/groups**: full LFS 13.0 `/etc/passwd` + `/etc/group`
  entries added so `systemd-network`, `systemd-resolve`, `systemd-logind`,
  etc. start correctly.
- **LFS libraries misplaced in `/usr/lib64`**: kmod/udev/systemd/dbus meson
  builds now use `-D libdir=/usr/lib`, so libs are loadable at runtime and
  dbus builds with systemd support (no more "compiled without systemd support").
- **Rootfs purge over-filtering**: `purge-rootfs.py` now preserves the genuine
  LFS dbus systemd units (`KEEP_EXACT`) while still stripping Ubuntu/build-tree
  contamination.
- **Installer merged-`/usr` symlinks**: relative symlink targets prevent any
  later host traversal (chroot, `os.RemoveAll`, ldconfig) from escaping into
  the live initrd root.
- **Serial console** enabled in the installed GRUB config for headless
  install/boot testing.

## Known limitations

- Installer targets BIOS/legacy boot on a single ext4 root partition; UEFI is
  not yet supported.
- Parallel Phase 3 builds are experimental (`PARALLEL_PHASE3` in `ginger.conf`).
- The build host must be Ubuntu 24.04 (or a compatible distro with
  `debootstrap`).

## Build from source

```bash
# 1. Build the LFS system (13 steps) via the orchestrator
./run.sh

# 2. Produce the ISO
./make-iso.sh

# 3. Test install
./test-installer.sh
./test-boot.sh
```

See [docs/WORKFLOW.md](../WORKFLOW.md) for the full workflow and
[README.md](../../README.md) for architecture.

## What's Changed
* Ginger OS v1.0.0-stable by @codewithwest in https://github.com/codewithwest/ginger_os/pull/3


**Full Changelog**: https://github.com/codewithwest/ginger_os/compare/1.0.0-beta...v1.0.0

GingerOS

// features

// usage

// release_notes — v1.0.0

// downloads