Show HN: I've built a nice home server OS

Minimal, container‑first, optimized for reliability and happiness.

Lightwhale makes Linux servers fun again.

No maintenance headaches.

Just boot and focus on what matters !

is a purpose-built operating system designed to run Docker containers effortlessly. It live-boots from an ISO straight into a fully functional Docker Engine, eliminating the need for installation or configuration.

The core system is immutable, making it inherently maintenance-free while enhancing security. Data and customisations are stored entirely segregated on a dedicated device, ensuring they never become entangled with core system files. This gives transparency and makes backup easier.

Streamlined yet versatile enough for home labs or enterprise, bare‑metal or virtualized, edge nodes or clusters.

Driven by a minimalistic design philosophy and an emphasis on ease of use, Lightwhale lowers the entry barrier, removes tedious administration tasks, and opens a friction-free path to productivity, and makes you feel awesome*!*

Let's get Lightwhale running on a bare‑metal x86 machine, in just a few easy steps.

Download the latest Lightwhale ISO file from the download section or copy, paste, and run this in your terminal:

curl -JOL http://lightwhale.asklandd.dk/download/lightwhale-3.0.0-x86.iso

Write the Lightwhale ISO file to a USB flash device, either using your favorite ISO burner tool, or simply use dd

.:

sudo dd bs=4M conv=fsync if=lightwhale-3.0.0-x86.iso of=/dev/sdx

Boot your machine on the newly prepared Lightwhale boot media. It may be necessary to disable safe boot in the BIOS first.

Username: op

Password: opsecret

Write the magic header to the desired storage device, typically an SSD or HDD. Write it to the block device (not a partition); for HDD use e.g. /dev/sda

(not /dev/sda1

); for NVME use e.g. /dev/nvme0n1

(not /dev/nvme0n1p1

). This will in turn erase all existing data on the device. On some systems it's necessary to wipe an existing partition table first before writing the magic header:

sudo dd if=/dev/zero bs=512 count=1 conv=notrunc of=/dev/nvmeØn1

echo "lightwhale-please-format-me" | sudo dd conv=notrunc of=/dev/nvmeØn1

Reboot to let Lightwhale detect the magic header and automatically create and mount the data filesystem.

sudo setup-wifi --ssid="my wifi name" --password="my wifi secret"

At this point it's business as usual:

docker run -it --rm busybox ps

Always take adequate security measures before exposing a server to the internet. Since everyone knows the default login and password of your new server, at the very least change that:

passwd op

The Lightwhale ISO can boot on bare‑metal or in a virtual machine, supporting both UEFI and classic BIOS. It uses a classic sysv‑like init system that keeps the startup process simple and transparent.

First, the boot loader loads the Linux kernel and the root filesystem into memory. The kernel initializes the hardware and then hands control to /init

.

The init

process reads /etc/inittab

, mounts a standard writable tmpfs

for /tmp

and /run

, and then executes the init scripts in /etc/init.d

.

Early during init, the writable data filesystem is mounted. It provides direct storage for Docker data and upper overlays for /etc

, /var

, and /home

. This effectively enables you to configure Lightwhale, and install and run containers, all on top of the immutable root filesystem. By default, the data filesystem is a volatile tmpfs

, but when persistence is enabled, a storage device is used instead.

After all filesystems and overlays are in place, the remaining services start, and Lightwhale is ready to serve containers.

This is what truly sets Lightwhale apart from conventional server operating systems*!*

The root filesystem is a static squashfs

image, compressed to save memory, and inherently immutable. An immutable kernel and root filesystem instantly brings a number of advantages in terms of simplicity, security, and reliability.

/bin/sh

, /lib/libc.so.6

, of course /usr/bin/[

. The immutable nature of Lightwhale offers clear advantages, but in order to install, configure, run containers, and write data, a writable filesystem is required. And for the system to be genuinely useful, such changes must persist across reboots.

Lightwhale provides both temporary and persistent writability through an automated subsystem activated early during startup. This mounts the data filesystem at /mnt/lightwhale-data

.

All data written by Lightwhale is kept within a single subdirectory: /mnt/lightwhale-data/lightwhale-state

. This in turn serves as the writable upper layer in an overlayfs

stack, with the immutable root as the lower layer.

By default, Lightwhale mounts a volatile tmpfs

as its data filesystem. When persistence is enabled, the data filesystem instead resides on a storage device and is mounted accordingly.

The data filesystem overlay does not cover the entire root filesystem; that would defeat the purpose of immutability and Lightwhale altogether. Instead, the writable overlays apply only to a few strategic directories:

/etc

sshd

settings. /var

/home

Docker is configured with its data root directory located directly on the data filesystem, where all Docker runtime data is stored, including images, containers, volumes, and network state:

/mnt/lightwhale-data/lightwhale-state/docker

Persistence must be enabled explictly by writing the magic header to the storage device to be used, e.g. /dev/sdx

:

echo "lightwhale-please-format-me" | sudo dd conv=notrunc of=/dev/sdx

Multiple storage devices are supported to have a magic header written, and will be assembled into a Btrfs RAID1 volume.

The next time Lightwhale boots up, it will detect the magic disk, format it, and make it the data filesystem

.

The persistence subsystem is initiated from /etc/init.d/S11persistence

, and proceeds through a sequence of detailed steps, executed fully automatically:

Scan all disks for a partition with the filesystem label lightwhale-data

.

If found, use it as the data filesystem and jump to step 6; otherwise proceed to step 2.

Scan all disks for the magic header, specifically this exact byte sequence at the very start of the device: lightwhale-please-format-me

.

If found, treat each as a magic disk and proceed to step 3; otherwise jump to step 6.

For each magic disk, create a swap partition labeled lightwhale-swap

, then create a Linux partition that uses the remaining space and label it lightwhale-data

. Then proceed to step 4.

Scan all disks for swap partitions labeled lightwhale-swap

and Linux partitions labeled lightwhale-data

. Treat each as a magic swap partition or magic data partition and proceed to step 5.

All magic swap partitions are formatted and labeled lightwhale-swap

.

If only a single magic data partition exists, format it with btrfs --data single --metadata dup

.

In case of multiple, join them into a RAID1 and format with btrfs --data raid1 --metadata raid1c

. Subvolumes are created for n@lightwhale-data

, @lightwhale-state

, and @lightwhale-state-snapshots

.

Label the data filesystem lightwhale-data

, so it can be detected in step 1 at next startup.

If a data filesystem was created or found, mount its subvolume @lightwhale-data

at /mnt/lightwhale-data

; otherwise mount a tmpfs

instead.

Prepare the immutable lower layer: Bind mount /etc

on /run/lightwhale/overlay/lower/etc

, and mirror the entire directory tree of the immutable root filesystem.

Prepare the writable upper layer: If not present, create a directory on the writable data filesystem at /mnt/lightwhale-data/lightwhale-state/overlay/upper/etc

.

Finally use overlayfs

to virtually merge the two layers and mount the overlay filesystem at /etc

. This effectively replaces the immutable