Installation

Installation Guide

Complete guide to installing NullOS on your system.

Prerequisites

Before installing NullOS, ensure you have:

• ✅ A working NixOS installation
• ✅ Git installed (nix-shell -p git)
• ✅ Nix flakes enabled
• ✅ Basic familiarity with NixOS concepts

Step 1: Enable Flakes

If you haven't already enabled flakes, add this to /etc/nixos/configuration.nix:

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Then rebuild:

sudo nixos-rebuild switch

Step 2: Clone the Repository

Clone NullOS to your home directory or preferred location:

git clone https://github.com/yourusername/NullOS.git ~/NullOS
cd ~/NullOS

Step 3: Configure Per-Machine Overrides

NullOS uses a machines/{hostname}/default.nix file for per-machine configuration, combining with machines/profiles/base.nix.

Create Your Machine Config

Create a new directory for your machine:

mkdir machines/yourhostname

Create machines/yourhostname/default.nix and customize:

{
  username = "youruser";
  hostname = "yourhostname";
  system = "x86_64-linux";
  
  # Select desktop environment: "hyprland", "kde", or null
  desktopEnvironment = "hyprland";
  
  # Set any feature overrides from base.nix
  enableSteam = true;
  useNvidiaPrime = false; 

  # You can also set arbitrary NixOS config here directly
  boot.devSize = "8G";
}

See Variables Reference for detailed explanations of all options.

Step 4: Generate Hardware Configuration

Generate hardware configuration for your machine:

nixos-generate-config --show-hardware-config > modules/system/hardware_yourhostname.nix

Step 5: Setup SOPS Secrets

You need to encrypt your secrets (like githubToken and passwords) using sops-nix.

1. If you don't have an age key, generate one:

   nix-shell -p age --run "age-keygen -o ~/.config/sops/age/keys.txt"

2. Update .sops.yaml in the root of the repo to include your public key.
3. Create the encrypted secrets file:

   nix-shell -p sops --run "sops machines/yourhostname/secrets.yaml"

4. Add the required secrets like githubToken. See Managing Secrets.

Step 6: Update Flake Configuration

Edit flake.nix to add your machine configuration.

Find the nixosConfigurations block and add your machine:

nixosConfigurations = {
  nslapt = mkSystem "nslapt" "pc";
  nspc = mkSystem "nspc" "pc";
  nsminipc = mkSystem "nsminipc" "server";
  
  # Add your new machine here (select "pc" or "server" profile)
  yourhostname = mkSystem "yourhostname" "pc";
};

Step 7: Build and Switch

To build and switch to your new configuration, first enter the dev environment:

nix develop

Then you can run the alias:

fr # Rebuild current machine
# OR
nh os switch --hostname yourhostname

First Build Tips

• Takes time: First build downloads and builds many packages
• Large download: Expect several GB of downloads
• Check logs: Watch for errors during build

Step 8: Reboot and Login

After successful build:

1. Reboot your system: sudo reboot
2. You should see SDDM login manager
3. Login with your user account
4. Hyprland (or KDE) should start automatically

Post-Installation

After logging in, proceed to First Steps to:

• Set your password
• Learn keybindings
• Customize your environment

Alternative Installation Methods

From Existing NixOS

If you have an existing NixOS installation:

1. Backup your current /etc/nixos/configuration.nix
2. Follow steps above
3. Can mix old config with NullOS by importing your old config as a module

Next Steps

• First Steps - Initial configuration
• Customization Guide - Make it yours
• Hyprland - Learn the window manager