A user-guide to create a Raspberry Pi (3B+, 4) cluster under NixOS and managed by NixOps.
In this guide, the nodes are all connected to a VPN server using Wireguard.
Table of contents
- NixOps deployment
Booting the Raspberry Pis
For the Raspberry Pi 4, a Hydra job build a SD Image for it. You can find the job here, just pick the latest successful job and download the image.
In order to boot NixOS on a Raspberry Pi 3B+ you'll have to build your own image. Find its Nix expression at
First of all, if your main computer is not ARM-based, you have to emulate ARM on your system.
- Add the following parameter to your NixOS configuration:
boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
Then make sure to rebuild your system via
- You can now build the image via this command (which might take a while depending on your computer)
nix-build '<nixpkgs/nixos>' -A config.system.build.sdImage --argstr system aarch64-linux -I nixos-config=sd-image.nix
You might find useful information on this wiki post.
Uncompress the image and flash it
- The image created will be compressed with the zst format, to decompress it use:
nix-shell -p zstd --run "unzstd nixos-sd-image-20.09pre242769.61525137fd1-aarch64-linux.img.zst
- You can now flash the image to your SD card! Example with
dd bs=4M if=nixos-sd-image-21.03pre262561.581232454fd-aarch64-linux.img of=/dev/mmcblk0 conv=fsync
Then, plug a keyboard and a screen via the HDMI/micro-HDMI ports.
To connect it to internet, either plug a Ethernet cable or connect to the wifi with:
wpa_supplicant -B -i wlan0 -c <(wpa_passphrase 'SSID' 'password')
First viable configuration
After booting on the Raspberry Pi, generate the configuration via:
Then, you can pull the default configuration
curl https://raw.githubusercontent.com/hugolgst/nixos-raspberry-pi-cluster/master/rpi4/default-configuration.nix > /etc/nixos/configuration.nix
After successfully booting your RPI3B+, you have to pull the default configuration file in
curl https://raw.githubusercontent.com/hugolgst/nixos-raspberry-pi-cluster/master/rpi3B%2B/default-configuration.nix > /etc/nixos/configuration.nix
Then tweak the configuration file as you want and rebuild/reboot the system
nixos-rebuild switch reboot
To manage the Raspberry Pi cluster, we can use NixOps.
First of all make sure to have it installed on your system:
nix-env -iA nixos.nixops
nix-shell -p nixops
or add it to your system packages in
Create the deployment
Create the deployment using this command
nixops create nixops/cluster.nix -d <your-deployment-name>
Then you can list all your deployments and check if yours is present with:
To have more information about the commands available and the tool in general, check the manual.
Make sure to have your ssh public key in the root authorized keys!
users.extraUsers.root.openssh.authorizedKeys.keys = [ "ssh-rsa ... host" ];
Deploy the configurations
You can tweak the configuration(s) in
nixops/cluster.nix and the
nixops/ files as you want.
In order to deploy the configuration you can use the
nixops deploy -d <your-deployment-name>