Main repo: codeberg.org/giggio/nixos_serverbase

This project provides a modular and reusable NixOS configuration, primarily targeted at building server environments for Raspberry Pi 4 and Gmktec G3 Plus, plus VirtualBox for testing.

It is structured as a Nix Flake that can be consumed by other projects to inherit a base server configuration while allowing specific machine customizations.

It can also run by itself for creating a default, base configuration, just to see how it works.

This is my personal base environment and is very opinionated, it won't necessarily work for you. Use it as you will, or don't use it at all and just use it for some ideas that could be useful.

Warning: Be careful with the ISO installer, it will overwrite the target system without prompting.

• modules/serverbase/ (directory): The core reusable module. It includes standard packages, Home Manager integration, encryption setup (SOPS), and general system settings.
• modules/lib.nix: Provides helper functions to build system artifacts (Pi4 images, VBox OVAs) and development shells.
• configuration.nix: A specific machine configuration (example: pi4) that imports the serverbase and applies host-specific settings.

You can import this project in your own flake.nix to build your custom servers.

Use nixosModules.default to get the base configuration (includes serverbase, sops, and home-manager).

{
  description = "NixOS configuration";
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
    serverbase = {
      url = "git+https://codeberg.org/giggio/nixos_serverbase.git?ref=main";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs =
    {
      nixpkgs,
      serverbase,
      flake-utils,
      ...
    }:
    let
      machines = [
        rec {
          name = "pi4";
          defaultArch = "aarch64";
          hardwareModule = serverbase.nixosModules.hardware.pi4;
          modules = [ ./machines/${name}/configuration.nix ];
          supportsIso = false;
          supportsImg = true;
        }
        rec {
          name = "gmktec1";
          defaultArch = "x86_64";
          hardwareModule = serverbase.nixosModules.hardware.gmktec;
          modules = [ ./machines/${name}/configuration.nix ];
          supportsIso = true;
          supportsImg = false;
          vmMemorySize = 8;
          vmDiskSize = 30;
        }
      ];
      nixosConfigurations = serverbase.nixosModules.lib.mkNixosConfigurations machines;
    in
    {
      inherit nixosConfigurations;
    }
    // flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = import nixpkgs { inherit system; };
      in
      {
        formatter = pkgs.nixfmt-tree;
        packages = {
          list_machines = serverbase.nixosModules.lib.list_machines { inherit pkgs machines; };
        }
        // serverbase.nixosModules.lib.mkInstallerPackages {
          inherit nixosConfigurations machines;
        };
        devShells.default = serverbase.nixosModules.lib.mkDevShell {
          inherit pkgs;
          inherit system;
        };
      }
    );
}

Available modules in nixosModules:

• default: Base list of modules (recommended).
• lib: Useful helper functions.
• hardware: Configuration for known hardware, both physical and virtual.

You can build a Raspberry Pi 4 image that can be used to create an installation SD card, or an ISO that can be used to install on Gmktec G3 Plus. You can also build a VirtualBox OVA that can be imported into VirtualBox.

See the above example with mkInstallerPackages.

If you copy this project's Makefile to your project, you can use it to easily build the artifacts. Run make help for more information.

It will take the information you add to the machines (see example above) to generate custom targets, so you could run out/nix/ova/pi4.ova to build the VirtualBox OVA, or out/nix/img/pi4.img.zst to build the Raspberry Pi 4 image, or out/nix/iso/gmktec1.iso to build the Gmktec G3 Plus ISO. You could also view the whole file system that will be generated by running make out/nix/system/pi4.

All examples are with gmktec1, but you should replace with the name of your machine.

1. Install VirtualBox;
2. Set up your secrets (see Secrets);
3. Build and import the VM with make import_pi4;
4. Start the vm with make start_gmktec1. This will connect to the serial port of the machine.
5. After the machine boots, you can also connect to it via SSH.

The secrets will be automatically added to a separate disk in the VM during the build process if using the provided scripts.

If you have problems, inspect the virtual machine configuration with VirtualBox after you import it, make sure it matches your hardware.

You can also use make create_gmktec1, which will create an empty VM but connect an .iso to it, and when it boots it will install the OS. This is useful to test the .iso installer. There is no similar way to test the .img installer.

This is not very helpful (as the servers will not do anything useful), but will help you get a sense of what you can do with this library.

You can use this repository directly to build the default machine (e.g., for testing or as a starting point):

1. Clone this repo and set up your secrets (see Secrets).

2. Build it with make out/nix/img/pi4.img.zst. Or build with nix:

   nix build .#pi4_img

3. Burn it into the SD card using the Raspberry Pi Imager. For the operating system, select the last option, "Use custom" and select the image.

4. Load the sd card into the Raspberry Pi 4.

5. Copy the secret file server.agekey to the root of a USB flash drive and connect the device to the Pi 4.

1. Clone this repo and set up your secrets (see Secrets).

2. Build it with make out/nix/iso/gmktec1.iso. Or build with nix:

   nix build .#gmktec1_iso

3. Burn it into the flash drive using your preferred tool. The easiest is to use dd (change sda for your device):

   sudo dd if=out/nix/iso/gmktec1.iso of=/dev/sda bs=4M status=progress

4. Load the flash drive into the Gmktec G3 Plus.

5. Copy the secret file server.agekey to the root of a USB flash drive and connect the device to the Gmktec G3 Plus.

Provides all necessary tools like SOPS, build utilities, etc.

nix develop
# or if you use direnv:
direnv allow

Run the integrated NixOS verification tests (boots a VM and runs checks):

nix flake check

Tests need more work and probably not working.

The sops secrets file should be at $HOME/.config/nixos-secrets/server.agekey. Generate the key file with:

nix shell nixpkgs#age -c age-keygen -o $HOME/.config/nixos-secrets/server.agekey

Update the .sops.yaml with the key:

1. View public key: grep public ~/.config/nixos-secrets/server.agekey
2. Update .sops.yaml (automated helper):

key=$(grep public ~/.config/nixos-secrets/server.agekey | sed 's/.*: //')
sed -i -E "s/(.*pi4 )(.*)( #)/\$key\3/" .sops.yaml

You need a gpg key to encrypt the secrets. You can find your fingerprint with:

gpg --with-colons --fingerprint | awk -F: '$1 == "fpr" {print $10; exit}'

If you have more than one key, this will print multiple lines. Choose the key that you need, or you can use all of them. Add the key to the .sops.yaml file, replacing the one that is there under giggio.

The secrets file is at ./modules/serverbase/secrets/shared.yaml. You can edit it with:

sops modules/serverbase/secrets/shared.yaml # if using the flake default shell with `nix develop` or `direnv`
# or
nix run nixpkgs#sops modules/serverbase/secrets/shared.yaml # if not using the flake default shell

You will need to use one of the keys listed in the .sops.yaml file. If you don't have it, remove the file and create a new one.

You can find the file layout by looking at ./modules/serverbase/secrets.nix.

Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on Codeberg.

Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests. Pull requests on Github will probably be ignored, so avoid them.

Giovanni Bassi

Licensed under the MIT license.