rpi-starter/
├── flake.nix                    # Main flake configuration and inputs
├── nixos/
│   ├── default.nix              # Core NixOS system configuration
│   ├── settings.nix             # Localization and system preferences
│   ├── hardware.nix             # RPi 4 hardware-specific settings
│   └── packages.nix             # System-level packages
├── home/
│   ├── default.nix              # Home Manager entry point
│   ├── packages.nix             # User packages
│   ├── git.nix                  # Git configuration
│   └── shell.nix                # Zsh, Tmux, Starship configuration
└── hosts/
    └── rpi-4/
        ├── configuration.nix    # Host-specific settings
        └── shell-functions.sh   # Custom shell utilities

Quick Start

1. Flash NixOS to SD Card

# Download aarch64 image
wget https://hydra.nixos.org/build/XXXXX/download/1/nixos-sd-image-aarch64-linux.img.zst

# Flash to SD card (replace sdX with your device)
zstdcat nixos-sd-image-aarch64-linux.img.zst | sudo dd of=/dev/sdX bs=4M conv=fsync

2. Boot and Setup Network

Boot the RPi 4 and find its IP address:

arp-scan -l
ssh root@<ip>  # Default password is empty

3. Clone Configuration

cd /tmp
git clone <your-repo> nixos-config
cd nixos-config

4. Apply Configuration

# Switch to new configuration
sudo nixos-rebuild switch --flake .#rpi-4

Customization

Change Username

Edit flake.nix:

primaryUser = "your-username";  # Change from "phil"

Add System Packages

Edit nixos/packages.nix:

environment.systemPackages = with pkgs; [
  # ... existing packages ...
  python3
  nodejs
];

Add User Packages

Edit home/packages.nix:

home.packages = with pkgs; [
  # ... existing packages ...
  poetry
  nodePackages.pnpm
];

Configure Git

Edit home/git.nix:

programs.git = {
  enable = true;
  userName = "Your Name";
  userEmail = "your@email.com";
  # ... more config
};

Customize Shell

Edit home/shell.nix for Zsh, Tmux, and Starship customizations.

Add Host-Specific Settings

Edit hosts/rpi-4/configuration.nix for RPi 4-specific packages and settings.

Available Commands

# Rebuild and switch to new configuration
rebuild

# Build without switching
rebuild-build

# Show system health (disk, memory, CPU, temp)
sys-health

# SSH into RPi
ssh-rpi [user] [host]

# Update flake inputs
flake-update

# Show largest directories
du-top

To use these commands, source the shell functions:

source hosts/rpi-4/shell-functions.sh

Or add to your zsh config to load automatically.

Configuration Files Overview

flake.nix

Declares inputs (nixpkgs, home-manager, etc.)
Defines outputs and system configuration
Entry point for the entire setup

nixos/default.nix

Main NixOS system configuration
Imports hardware, settings, and packages modules
Configures SSH, users, Nix settings

nixos/hardware.nix

RPi 4 bootloader and kernel settings
Filesystem and swap configuration
RPi 4-specific hardware enablement

nixos/settings.nix

Timezone and locale settings
Console keyboard layout
General system preferences

nixos/packages.nix

System-level packages available to all users

home/default.nix

Home Manager entry point
Imports shell, git, and packages modules
Sets home state version

home/packages.nix

User-level packages

home/git.nix

Git configuration (name, email, core settings)

home/shell.nix

Zsh configuration (aliases, keybindings, plugins)
Tmux configuration (prefix, keybindings)
Starship prompt setup
Direnv integration

hosts/rpi-4/configuration.nix

Host-specific package additions
RPi 4-specific customizations

hosts/rpi-4/shell-functions.sh

Bash functions for common tasks
Can be sourced in shell configs

Locale and Timezone

Default settings:

Timezone: Europe/Berlin
Locale: en_US.UTF-8 (with German regional settings)

Change in nixos/settings.nix:

time.timeZone = "America/New_York";
i18n.defaultLocale = "en_US.UTF-8";

Troubleshooting

SSH Connection Issues

Ensure SSH is enabled in nixos/default.nix
Check public key is authorized
Verify hostname resolves: ping rpi-4.local

Out of Memory

Increase swap in nixos/hardware.nix:

swapDevices = [{
  device = "/swapfile";
  size = 4096;  # Increase to 4GB
}];

Package Not Found

# Search for a package
nix search nixpkgs package-name

# Add to appropriate .nix file and rebuild

Rebuild Fails

# Update flake inputs
nix flake update

# Check for errors
nix flake check

Useful Nix Commands

# Update all inputs to latest versions
nix flake update

# Check flake for errors
nix flake check

# Show flake outputs
nix flake show

# Search for packages
nix search nixpkgs <n>

# Inspect package
nix eval -f '<nixpkgs>' 'hello.meta.description'

Resources

Notes

State version: 24.11 - update if needed
Store auto-optimizes weekly and cleans packages older than 30 days
Flakes and nix-command are enabled by default
Change primaryUser from "phil" to your username