❄️ dot.nix

My NixOS & Home Manager Multi User/Host Configuration
A modular Nix flake managing multiple systems and users with a focus on reproducibility and ease of maintenance.

🏗️ Architecture Overview

This repository follows a layered, modular approach that separates system-level configurations from user environments, while promoting code reuse across different hosts and users.

📁 dot.nix/
├── ❄️ flake.nix                    # Central entry point & dependency management
├── 🔐 secrets.nix                  # Encrypted secrets (git-crypt)
├── 🏠 hosts/                       # System-level configurations
├── 👤 home/                        # User environment configurations  
├── 📦 modules/                     # Reusable configuration modules
├── 🎨 overlays/                    # Package customizations
├── 📋 pkgs/                        # Custom package definitions
└── 🛠️ lib/                         # Helper functions & utilities

---

🎯 Core Components

Flake Management (flake.nix)

The heart of the configuration, managing:

• External Dependencies: nixpkgs, home-manager, stylix, hardware modules, solaar, snapraid-aio, chaotic
• System Outputs: Complete NixOS configurations for each host
• Custom Packages: Exposed packages from pkgs/
• Overlays: Package modifications and additions

Secret Management

• Encryption: git-crypt secures sensitive data in secrets.nix
• Structure: Defined by modules/global/secret-spec.nix
• Content: SSH keys, API tokens, hashed passwords, SMTP credentials

Configuration Specifications

• host-spec.nix: Defines host attributes (hostname, user, hardware type, desktop environment, isMinimal for server configurations)
• secret-spec.nix: Structures for secrets, firewall rules, Docker environments, Users, etc
  • Example secrets.nix

---

🏠 System Architecture (hosts/)

Global Configurations

hosts/global/
├── core/                           # Essential base settings
│   ├── fonts.nix                   # Font management
│   ├── networking.nix              # Network configuration
│   ├── ssh.nix                     # SSH server setup
│   └── user.nix                    # User account setup
└── common/                         # Optional system features
    ├── audio.nix                   # PipeWire audio stack
    ├── gaming.nix                  # Steam, GameMode, hardware optimizations
    ├── gnome.nix                   # GNOME desktop environment
    ├── docker.nix                  # Docker setup
    └── libvirt.nix                 # VM tools and management

Host-Specific Configurations

Each system in hosts/nixos/<hostname>/ contains:

• default.nix: Main configuration importing globals + host-specific settings
• hardware.nix: Hardware-specific configuration (bootloader, filesystems, drivers)
• config/: Service-specific configurations (optional)

🖥️ Current Hosts

Host	Type	Purpose	Hardware	Services
rune	Desktop	My workstation	Ryzen 9 7900X3D, RX 9070 XT	Gaming, Development, VMs
gojo	Desktop	Giovanni's workstation	Ryzen CPU, RX 6950 XT	Gaming, Development
haze	Desktop	Cesar's workstation	Ryzen 7, RX 6950 XT	Gaming, Development
sock	Server	Backup & Storage	Intel N150	WIP; Hosted on Firewall
cloud	LXC Container	Storage & NFS	4C/4GB	File storage, NFS server, Backups
komodo	LXC Container	Docker orchestration	12C/30GB	Authentik, Komodo, Web services
proxy	LXC Container	Network proxy	3C/2GB	Cloudflare tunnels, Caddy
nix	LXC Container	Development server	10C/12GB	Remote development, VSCode server
vm	VM	Testing environment	Variable	System testing

---

👤 User Environment (home/)

Global Home Configurations

home/global/
├── core/                           # Essential user tools
│   ├── fastfetch/                  # System info shell prompt with custom scripts
│   ├── fish/                       # Shell configuration
│   ├── git.nix                     # Git setup with signing
│   └── ssh.nix                     # SSH client configuration
└── common/                         # Optional user applications
    ├── gaming/                     # Gaming tools & emulator backups
    ├── gnome/                      # GNOME-specific programs & settings
    ├── vscode/                     # VS Code with patched SSH
    └── zen.nix                     # Zen browser configuration

User-Specific Configurations

Each user in home/users/<username>/ includes:

• Theme Configuration: Stylix-based theming with custom color schemes
• Host Adaptations: Per-host overrides in home/hosts/<hostname>/

👥 Current Users

User	Theme	Primary Host	Desktop Setup
toph	Invincible (blue/yellow)	rune	GNOME + PaperWM
gio	Gojo (red/white)	gojo	GNOME + PaperWM
cesar	Soraka (purple/violet)	haze	GNOME + PaperWM

---

🎨 Theming & Customization

Stylix Integration

• Unified Theming: Base16 color schemes applied system-wide
• Custom Schemes: User-specific YAML color definitions
• Coverage: GTK, terminal (ghostty), VS Code (optional), wallpapers
• Fonts: Consistent typography (Lexend, Monocraft Nerd Fonts, Laila)

GNOME Customization

• Window Management: PaperWM for tiling workflow
• Extensions: Blur My Shell, Vitals, Pano clipboard, custom keybindings, ...
• Per-User: Customized dconf settings for each user's workflow

---

🔧 Notable Features

🎮 Enhanced Gaming

• Optimized Stack: Steam integration with Proton, GameScope, and GameMode.
• Automated Emulator Backups: borg-wrapper script (Fish-based) leverages inotify-tools and borgbackup for automatic, incremental save file backups for emulators like Ryujinx.

  # Example: Automatic save backup for Ryujinx
  borg-wrapper -p "~/.config/Ryujinx/bis/user/save" \
               -o "/pool/Backups/Switch/RyubingSaves" \
               -m 30 -- ryujinx
  

• Hardware Tuning: Includes AMD GPU specific settings (e.g., lact for tuning) and Variable Refresh Rate (VRR) support.

🗄️ Robust Storage & Backups

• Centralized Storage (Cloud Host): Utilizes a MergerFS pool for unified drive access, exported via NFS (mounted as /pool on other hosts).
• Data Integrity: SnapRAID provides parity-based data protection for the storage pool.
• Comprehensive Backups: Provides incremental backups of critical data, like Docker volumes and Forgejo instances, with Apprise notifications.
• Automated Backup Chain: Systemd timers orchestrate SnapRAID syncs and Borg backups.

🖥️ Streamlined Desktop & User Experience

• Custom Fish Shell: Enhanced with the Tide prompt, grc for colorized output, and some utility functions
• Modern Terminal: ghostty as the default terminal emulator, themed with Stylix.
• Efficient File Management: yazi configured as the terminal file manager.
• Curated Applications: Includes configurations for applications like the Zen browser and VS Code.
• XDG & Mime Associations: Sensible default applications configured via xdg.mimeApps, using handlr-regex for flexibility.

🐳 Container Management

• Komodo Integration: Docker stack management through web UI
• Service Definitions: Authentik SSO, Caddy reverse proxy, various applications
• compose2nix: Docker Compose files converted to NixOS modules

🐳 Advanced Container Management

• Docker Orchestration: Komodo provides a web UI for managing Docker stacks.
• Key Services: Pre-defined declarative configurations for services like Authentik (SSO) and Caddy (reverse proxy).
• Declarative Stacks: compose2nix is used to convert Docker Compose files into NixOS declarative modules for services like FileRun, Authentik, etc.

🔐 Integrated Security

• Encrypted Secrets: git-crypt for managing sensitive data in git.
• Secure Remote Access: Cloudflare Tunnels for Zero Trust access to services.
• Automated Certificates: ACME (Let's Encrypt) with DNS challenges for SSL/TLS.
• SSH Key Deployment: Automated management and deployment of SSH keys.

---

🚀 Usage & Deployment

Initial System Installation

For setting up a new system (in NixOS) with this configuration:

1. Clone Configuration Repository

# Get yay.nix temporarily for installation
nix shell github:Tophc7/yay.nix --extra-experimental-features flakes --extra-experimental-features nix-command --no-write-lock-file

# Clone the configuration repository using yay try
yay try git git-crypt micro
cd ~/Documents/
git clone https://github.com/tophc7/dot.nix

2. Unlock Encrypted Secrets

cd ~/Documents/dot.nix
git-crypt unlock <<path/to/symmetric.key>> # Or use GPG key

3. Configure Hardware Settings

1. Compare hardware configurations:

   micro ~/Documents/dot.nix/hosts/nixos/gojo/hardware.nix
   micro /etc/nixos/hardware-configuration.nix
   

2. Update hardware.nix with the fileSystems and swapDevices from the generated /etc/nixos/hardware-configuration.nix

4. Install Configuration (TTY)

1. Switch to TTY: Ctrl+Alt+F2
2. Login to TTY
3. Rebuild system:

   nix shell github:Tophc7/yay.nix --extra-experimental-features flakes --extra-experimental-features nix-command --no-write-lock-file
   yay rebuild -H gojo -p ~/Documents/dot.nix -e
   sudo reboot -f
   

Day-to-Day System Management

Once installed, use the integrated yay tool for all system management:

# Build and switch system configuration
yay rebuild

# Update flake inputs
yay update

# Clean up system
yay garbage

# Try packages temporarily
yay try fastfetch -- fastfetch

# Create archives
yay tar myfiles/

# Extract archives  
yay untar myfiles.tar.zst

Environment Variables

• FLAKE: Set to your flake directory to avoid using -p flag repeatedly

  export FLAKE="$HOME/Documents/dot.nix"
  yay rebuild  # Will automatically use $FLAKE path
  

---

📚 Development Philosophy

Modularity

• Separation of Concerns: System vs. user configurations
• Reusable Components: Shared modules across hosts
• Parameterization: Host specs drive configuration choices

Maintainability

• Structured Secrets: Clearly defined secret specifications
• Documentation: Inline comments and clear naming
• Testing: VM configurations for safe testing

Flexibility

• Multiple Users: Support for different users with different preferences
• Host Adaptation: Same user config adapts to different machines
• Service Composition: Mix and match services per host needs

---

🔗 Key Technologies

Category	Technologies
Core	NixOS, Home Manager, Nix Flakes
Shell	Fish Shell, Tide Prompt
Desktop	GNOME, PaperWM, Stylix, Ghostty, Yazi
Virtualization	libvirt, QEMU, LXC
Storage	MergerFS, SnapRAID, BorgBackup, NFS, inotify-tools
Containers	Docker, Komodo, compose2nix
Security	git-crypt, ACME, Cloudflare Tunnels
Development	VS Code (Patched SSH), nixfmt, biome
Gaming	Steam, Proton, GameScope, GameMode, lact
Monitoring	Apprise notifications, systemd timers

---

📝 Quick Reference

Directory Structure

• hosts/nixos/<name>/ - System configurations
• home/users/<name>/ - User environments
• home/hosts/<name>/ - Host-specific user overrides
• modules/global/ - Shared specifications
• pkgs/ - Custom packages
• secrets.nix - Encrypted secrets (git-crypt)

Key Files

• flake.nix - Dependency management & outputs
• shell.nix - Recovery environment
• modules/global/host-spec.nix - Host attribute definitions
• modules/global/secret-spec.nix - Secret structure definitions

---

👥 Credits & Acknowledgments

This configuration is built upon the excellent foundation provided by EmergentMind's configuration. Many core architectural decisions and implementation patterns draw heavily from their work, including but not limited to:

• Host Specification System: The host-spec.nix pattern and mkHost function structure
• Modular Architecture: The separation of system and user configurations

A huge thank you to EmergentMind for creating such a well-structured and educational NixOS configuration that serves as my introduction to NixOS and its wonders. Their work made this homelab setup possible and continues to influence It.

---

This configuration emphasizes reproducibility, security, and maintainability while supporting a complex multi-user, multi-host homelab environment. I quite love it, hope it serves as inspo to some of you out there.