nix-config

NixOS flake configuration managing multiple hosts with modular architecture, automated secret management, and k3s cluster orchestration.

Features

• 🏗️ Modular Architecture - Reusable components with explicit enable flags
• 🔐 SOPS Secret Management - Age-encrypted secrets with placeholder substitution
• 🐳 k3s Cluster - Raspberry Pi control plane with x86_64 worker nodes
• 🏠 Home Automation - Home Assistant, Zigbee2MQTT, Mosquitto on ARM64
• 🖥️ Multi-Architecture - x86_64 desktops and ARM64 Raspberry Pi with cross-compilation
• 🔄 Automated Deployment - Network deployment with deploy-rs, token rotation tools

Hosts

Host	Platform	Role	Key Features
rincon	x86_64 (ThinkPad X1 Gen 12)	Laptop	Fingerprint reader, Azure CLI, Docker
solimar	x86_64 (Desktop)	k3s Worker	General compute, NVIDIA RTX 2060, Frigate NVR
laconchita	x86_64 (Desktop)	k3s Worker	AI/ML compute, NVIDIA RTX 3090, Coral TPU
faria	ARM64 (RPi 4)	k3s Control Plane	Home automation, IoT hub
mondos	x86_64 (ThinkPad X280)	Laptop	Ultraportable, 8th gen Intel

Quick Start

# Clone repository
git clone <repository-url> && cd nix-config

# Configure secrets
sops secrets.yaml

# Build and deploy
sudo nixos-rebuild switch --flake .#<hostname>

📖 Full setup instructions: Quickstart Guide

Documentation

Getting Started

• Quickstart Guide - Initial setup and deployment
• Architecture Overview - System design and patterns
• Network Topology - Network and service architecture

Operations

• Secret Management - SOPS encryption and secret access patterns
• Raspberry Pi Deployment - ARM64 cross-compilation and SD card creation
• k3s Token Management - Cluster token rotation
• Troubleshooting - Common issues and solutions

Common Commands

# Build and deploy
sudo nixos-rebuild switch --flake .#<hostname>

# Build ARM64 SD image
nix build .#packages.x86_64-linux.faria

# Deploy to Raspberry Pi
deploy .#faria

# Rotate k3s token
nix run .#rotate-k3s-token

# Edit secrets
sops secrets.yaml

# Home Manager
home-manager switch --flake .

Architecture

Directory Structure

nix-config/
├── flake.nix           # Flake orchestration and outputs
├── hosts/              # Host-specific configurations
│   ├── rincon/
│   ├── solimar/
│   ├── laconchita/
│   └── faria/
├── modules/            # Reusable modules (disabled by default)
│   ├── desktop/        # GNOME, printing, scanning
│   ├── hardware/       # GPU, TPU, platform-specific
│   ├── services/       # k3s, Frigate, Home Assistant
│   └── system/         # Users, SOPS, base configuration
├── hardware/           # Hardware profiles
├── systems/            # Base system configuration
├── users/              # Home-manager configurations
├── docs/               # Documentation
└── scripts/            # Automation scripts

Module System

All modules follow the pattern:

{ lib, config, ... }:
let cfg = config.modules.<category>.<name>;
in {
  options.modules.<category>.<name>.enable = lib.mkEnableOption "description";
  config = lib.mkIf cfg.enable {
    # Module implementation
  };
}

Modules are composed in host configurations like building blocks.

k3s Cluster

graph TB
    Internet((Internet))

    subgraph Cloud["☁️ AWS Cloud"]
        Bastion["🌐 Bastion<br/>Cloud VM<br/>Public Access"]
    end

    subgraph HomeNet["🏠 Home Network"]
        subgraph K3s["k3s Cluster"]
            Control["🎛️ faria<br/>Raspberry Pi 4<br/>ARM64<br/>Control Plane"]

            Worker1["⚡ solimar<br/>AMD Ryzen<br/>RTX 2060<br/>General Compute"]
            Worker2["🤖 laconchita<br/>Intel<br/>RTX 3090 + Coral TPU<br/>AI/ML Workload"]
        end
    end

    Internet -->|HTTPS| Bastion
    Bastion -.->|Tailscale VPN| Control
    Control ==>|k3s API<br/>:6443| Worker1
    Control ==>|k3s API<br/>:6443| Worker2

    classDef cloud fill:#FF9900,stroke:#232F3E,stroke-width:2px,color:#fff
    classDef control fill:#326CE5,stroke:#fff,stroke-width:2px,color:#fff
    classDef worker fill:#00D4AA,stroke:#fff,stroke-width:2px,color:#fff
    classDef aiml fill:#E91E63,stroke:#fff,stroke-width:2px,color:#fff

    class Bastion cloud
    class Control control
    class Worker1 worker
    class Worker2 aiml

Loading

Architecture:

• Control Plane: faria (ARM64) - k3s server, home automation hub
• General Compute: solimar (RTX 2060) - Frigate NVR, media services
• AI/ML Workload: laconchita (RTX 3090 + Coral TPU) - AI/ML compute with GPU taints
• External Access: AWS bastion connected via Tailscale VPN

Secret Management

Secrets are encrypted with SOPS-nix and age encryption:

# Edit secrets
sops secrets.yaml

# Access in configuration (two patterns)
config.sops.placeholder."key"      # Placeholder substitution for generated configs
config.sops.secrets."key".path     # Runtime path for file-based access

📖 Complete guide: Secret Management

Development

Prerequisites

• NixOS with flakes enabled
• SOPS and age for secret management
• Deploy-rs for remote deployment (optional)

Building

# Validate configuration
nixos-rebuild build --flake .#<hostname>

# Test in VM (x86_64 only)
sudo nixos-rebuild build-vm --flake .#<hostname>
./result/bin/run-<hostname>-vm

Contributing

1. Create logical, atomic commits
2. Use conventional commit format (feat/fix/refactor/docs/chore)
3. Remove trailing whitespace: nowhite ./
4. Test builds before pushing

License

Personal configuration repository. Use at your own risk.

References

• NixOS Manual
• Home Manager Manual
• SOPS-nix
• deploy-rs