Init
This commit is contained in:
271
README.md
Normal file
271
README.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user