NixOS-Configs/README.md

NixOS-Configs

My NixOS system configurations managed with Nix flakes, home-manager, and colmena for multi-host deployment.

Overview

This repository contains NixOS configurations for multiple hosts including workstations, servers, and Raspberry Pi systems. It uses:

• Nix Flakes for reproducible builds and dependency management
• home-manager for user environment configuration
• colmena for multi-host deployment
• sops-nix for secrets management
• Role-based configuration for modular host setup

Host Categories

Workstations

• loki - Framework AMD AI 300 (primary development machine)
• book - Google Pixelbook 2017
• dragon - Custom workstation
• ace - Acer C720
• eve - Google Pixelbook 2017 (eMMC)
• pocket2 - Mobile workstation
• smaug - ThinkPad x260

Servers

• w1 - Hetzner VPS
• fred - Acer server
• harper - Server
• harper2 - Server
• nuwww - Web server
• www2 - Web server
• pihole - Pi-hole server

Raspberry Pi Systems

• pi1 - Raspberry Pi
• display - Pi 4 with kiosk display

Virtual Machines

• vm - Generic VM
• vm1 - VM configuration

Quick Start

Prerequisites

• Nix with flakes enabled
• Age key for secrets decryption (see secrets section)

Building a Host

# Test build without installing
just test <hostname>

# Apply configuration to host
just switch <hostname>

# Apply and reboot
just bootswitch <hostname>

Updating

# Update flake.lock
just update

# Apply updates to all hosts
just world

Available Commands

• just test <host> - Build and validate configuration
• just switch <host> - Apply configuration
• just boot <host> - Apply configuration for next boot
• just world - Deploy to all hosts
• just workstation - Deploy to workstation hosts
• just server - Deploy to server hosts
• just web - Deploy to web hosts
• just clean <host> - Clean old generations and optimize store
• just update - Update flake.lock
• just format - Format Nix code

Configuration Structure

Host Configuration

Each host in hosts/<hostname>/ follows this pattern:

{
  imports = [ ../templates/workstation.nix ];  # Base template
  
  networking.hostName = "hostname";
  variables.address = "100.72.x.x";  # Tailscale IP
  
  roles = {
    gui.enable = true;
    games.enable = true;
    wm = "sway";
  };
}

Roles

Hosts are configured using role-based modules:

• gui - Graphical user interface packages
• games - Gaming packages and Steam
• citrix - Citrix Workspace client
• zoom - Zoom client
• kvm - Virtualization support
• kmscon - Console improvements
• auto-cpufreq - CPU power management

Window Managers

• sway - Wayland compositor (default for workstations)
• gnome - GNOME desktop environment

Home Manager

User configurations are managed separately:

• home/common/ - Common packages and settings for all users
• home/gui/ - GUI-specific user configuration
• home/work/ - Work-related packages and settings

Secrets Management

Secrets are encrypted using sops-nix with Age keys.

Setup

1. Generate Age key pair:

   nix run nixpkgs#age -- -generate-keypair
   

2. Add public key to .sops.yaml:

   keys:
     - &host_<name> <public_key>
   creation_rules:
     - path_regex: secrets.yaml$
       key_groups:
         - age:
           - *host_<name>
   

3. Encrypt secrets:

   sops --encrypt secrets.yaml > secrets.yaml.enc
   

Usage in Configuration

# In host configuration
sops.secrets."service/password".path

Development

Adding a New Host

1. Create hosts/<hostname>/default.nix
2. Add hardware configuration if needed
3. Import appropriate template (workstation.nix, server.nix, etc.)
4. Configure roles and variables
5. Add to flake.nix outputs
6. Test with just test <hostname>

Template Types

• hosts/templates/workstation.nix - Full desktop/workstation
• hosts/templates/server.nix - Server configuration
• hosts/templates/pi-server.nix - Raspberry Pi server

Code Quality

• Format code: just format
• Check configuration: nix flake check
• Validate secrets: Ensure .sops.yaml has correct public keys

Troubleshooting

Common Issues

• Build fails: Check nix flake show for syntax errors
• Secrets not found: Verify Age key is in ~/.config/sops/age/keys.txt
• Network issues: Check Tailscale connectivity
• Home manager conflicts: Remove backup files: locate home-manager-backup | xargs rm

Logs

Build logs are saved to nixos-switch.log. Check this file for detailed error information.

Contributing

1. Test changes on a single host first
2. Update documentation for new features
3. Clean up FIXME/DELME comments
4. Format code before committing