HomestakerOS is a declaratively managed Linux distribution for Ethereum homestaking. Nodes can be managed either through a web UI or via text files. Compared to Docker-based approaches which build on Ubuntu and the apt package manager, HomestakerOS builds on NixOS and the Nix package manager. And by building, we really mean building: both the web UI and the text files are actually instructions how to derive a self-contained Linux disk images (akin to ISO files) from zero. By self-contained we mean that once the image is booted, there are no further commands to run for the node become operational. A unique aspect of HomestakerOS is that you never "install" HomestakerOS, but instead you run it as an ephemeral RAM disk (a.k.a "live CD").
This repository contains open-source software tooling to create such images.
The main contribution is the web UI at HomestakerOS.com and its NixOS configuration page, which allows you to configure and build homestaking nodes using a web UI.
The main artifacts returned by the build process endorse kexec as the boot approach: given an existing Linux installation, executing the kexec-boot file jumps the existing Linux into HomestakerOS.
The web UI also returns you a pre-configured NixOS system template.
Compared to Docker-based alternatives, this bootstraps you with more control over your node: you can manage the whole Linux distribution rather than only the Ethereum client software.
The main practical benefit of the approach endorsed by HomestakerOS is improved system reliability. Tragicomically and anecdotally, Linux is easier to manage and troubleshoot when you delete it (so-called "erase your darlings" paradigm) on each boot. This does not mean deleting everything -- blockchain state and other so-called "persistent" files are saved in an opt-in manner via disk mounts.
To get started, there exists a live demo which uses a publicly shared multi-node cluster: https://homestakeros.com/ponkila/homestaking-infra.
-
Install Nix nixos.org
-
Clone this Repository
git clone https://github.com/ponkila/HomestakerOS && cd HomestakerOS -
Start the backend
nix run .#backend -
Set the flake URI as
<github-username>/<repository-name> -
Click 'Submit' to load your configurations
This project was inspired by the challenges encountered while managing our existing Ethereum infrastructure. The lack of knowledge about the setup and configuration of other maintainers' nodes within the same infrastructure leads to wasted time, effort, and downtime. The declarative nature of NixOS configurations, combined with the ephemeral approach, significantly enhances management and collaboration among team maintainers. It ensures that configurations are centralized and real-time information about the whole infrastructure is easily accessible by all participants.
You can see our running, real-time infrastructure right in homestaking-infra.
In the web user interface, you will configure your node under the 'NixOS config' tab. You can select the Ethereum client(s) and any additional addons. The packages for these mainly come from ethereum.nix and are frequently updated by the collaborators who use them. We look forward to adding more components on-demand and preferably upstreaming them if we package them ourselves.
For those interested in the details, let's dive into the documentation from here.
-
Learn how to set up your machine for deploying HomestakerOS, including essential setup and configurations.
-
This is our entry-level guide to Ethereum and homestaking.
-
3. 📘 Working with Nix (outdated)
An in-depth explanation of the HomestakerOS workflow, including the initialization process and build process.
-
Explore Nixie, a project designed for deploying and managing ephemeral operating systems.
HomestakerOS is still a work in progress, and while it has previously received support from a grant by the Ethereum Foundation and ssv.network, we are actively seeking additional funding and support to continue development. If you're interested in contributing or funding this project, please reach out!