cyper-rpi/README.md

# NixOS Starter for Raspberry Pi 4

A declarative NixOS flake setup for Raspberry Pi 4, following a modular configuration structure.

## Directory Structure

```
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

```bash
# 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:

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

### 3. Clone Configuration

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

### 4. Apply Configuration

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

## Customization

### Change Username

Edit `flake.nix`:
```nix
primaryUser = "your-username";  # Change from "phil"
```

### Add System Packages

Edit `nixos/packages.nix`:
```nix
environment.systemPackages = with pkgs; [
  # ... existing packages ...
  python3
  nodejs
];
```

### Add User Packages

Edit `home/packages.nix`:
```nix
home.packages = with pkgs; [
  # ... existing packages ...
  poetry
  nodePackages.pnpm
];
```

### Configure Git

Edit `home/git.nix`:
```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

```bash
# 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:

```bash
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`:

```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`:

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

### Package Not Found
```bash
# Search for a package
nix search nixpkgs package-name

# Add to appropriate .nix file and rebuild
```

### Rebuild Fails
```bash
# Update flake inputs
nix flake update

# Check for errors
nix flake check
```

## Useful Nix Commands

```bash
# 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

- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
- [Home Manager Manual](https://nix-community.github.io/home-manager/)
- [Nix Flakes Guide](https://nixos.wiki/wiki/Flakes)
- [RPi NixOS Guide](https://nixos.wiki/wiki/NixOS_on_ARM/Raspberry_Pi)

## 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