NixOS Configuration

Overview

This repository contains a complete NixOS system configuration that follows modern best practices:

• Uses the Nix Flakes feature for reproducible builds and dependency management
• Employs a modular architecture to separate concerns and improve maintainability
• Integrates home-manager for user-level configuration management
• Supports multiple host configurations with shared modules
• Includes tools for secrets management, persistence, deployment, and testing

Key Features

• Modular Design: System configuration split into logical, reusable components
• Multi-Host Support: Define multiple systems with shared configurations
• Home Manager Integration: User configurations managed alongside system configs
• Impermanence: Support for ephemeral root with persistent state
• Secret Management: Secure secrets handling with Agenix
• Deployment Tools: Remote deployment with deploy-rs
• Development Environment: Comprehensive dev tools and testing framework

Directory Structure

Directory	Description
flake.nix	Main flake entry point
flake-module.nix	Root flake module imported by flake.nix
hosts/	Host-specific configurations
home/	User home configurations via home-manager
modules/	Shared NixOS and home-manager modules
packages/	Custom packages
overlays/	Nixpkgs overlays
lib/	Custom library functions
dev/	Development tools and tests

Quick Start

Installation

To install this configuration on a new system:

# Clone the repository
git clone https://github.com/occhima/nixos.git ~/.config/nixos

# Build and switch to the configuration for your host
cd ~/.config/nixos
just switch

Available Commands

This repository uses just as a command runner. Here are the key commands:

# List all available commands
just

# Switch to the new system configuration
just switch

# Apply home-manager configuration
just home-switch

# Test configuration without applying
just test-switch

# Update flake lock file
just update

# Format code
just fmt

# Run tests
just test

# Clean the nix store
just clean

Adding a New Host

1. Create a new directory under hosts/ for your host
2. Add a default.nix file with the host-specific configuration
3. Update hosts/flake-module.nix to include the new host in hosts attribute
4. Configure deployment settings in hosts/deploy.nix if needed

Adding a New User

1. Create a user config file in modules/nixos/accounts/users/
2. Add the user to allUsers in modules/nixos/accounts/accounts.nix
3. Create a home-manager configuration in home/username/
4. Enable the user by adding to enabledUsers in your host configuration

Architecture

Flake Structure

This configuration uses flake-parts to organize the flake into modular components:

• flake.nix - Entry point with input definitions
• flake-module.nix - Root module that composes all components
• Component flake modules:
  • hosts/flake-module.nix
  • home/flake-module.nix
  • modules/flake-module.nix
  • overlays/flake-module.nix
  • packages/flake-module.nix

Host Configuration

Hosts are defined in hosts/ with a structure that follows:

hosts/
├── hostname/
│   ├── default.nix    # Main system configuration
│   ├── hardware.nix   # Hardware-specific settings
│   └── disko.nix      # Optional disk partitioning config
├── flake-module.nix   # Exports nixosConfigurations
├── deploy.nix         # Deployment configuration
└── profiles/          # Shared profiles for similar systems
    ├── common/        # Configurations shared by all hosts
    ├── desktop/       # Desktop-specific configurations
    ├── headless/      # Server configurations
    ├── iso/           # ISO image configurations
    └── wsl/           # Windows Subsystem for Linux configs

Home Manager Integration

Home Manager is integrated in two ways:

1. NixOS Module - For users on NixOS systems via modules/nixos/accounts/accounts.nix
2. Standalone - For users on non-NixOS systems via home/flake-module.nix

Each user’s configuration is stored in home/username/.

Modules System

The modules/ directory contains reusable configuration modules:

modules/
├── flake-module.nix
├── nixos/                # System-level modules
│   ├── accounts/         # User account management
│   ├── hardware/         # Hardware-specific configs
│   ├── network/          # Networking configurations
│   ├── system/           # Core system settings
│   └── ...
└── home-manager/         # User-level modules
    ├── data/             # XDG and persistence
    ├── desktop/          # Desktop environment
    ├── shells/           # Shell configurations
    └── ...

Secrets Management

This configuration uses agenix for secrets management:

• Keys are stored in hosts/secrets/identity/
• Encrypted secrets are in hosts/secrets/vault/
• Rekey functionality via agenix-rekey facilitates key rotation

State Persistence

The configuration supports ephemeral root with persistent state via the impermanence module:

• System-level persistence in modules/nixos/system/file-system/impermanence.nix
• User-level persistence in modules/home-manager/data/persistence.nix

Development

Development Environment

To set up the development environment:

# Enter development shell with all tools
nix develop

# Reload development environment
just reload

Testing

Tests can be run with:

# Run all tests
just test

# Run Nix unit tests
nix run ./dev#test

Code Formatting

The codebase uses treefmt for formatting:

# Format all files
just fmt

Pre-commit Hooks

Pre-commit hooks are configured in dev/pre-commit.nix and can be run with:

just pre-commit

Documentation

Comprehensive documentation is available in the docs directory. The documentation includes:

• Installation guide
• Adding new hosts and users
• Module documentation
• Development workflow

The documentation can be built with MkDocs. See the docs README for instructions.

Roadmap

The following features are planned for implementation:

• [ ] Use devenv or any other to define multiple developer environments
• [ ] Stylix + themes
• [ ] Devenv + dev profiles
• [ ] Colmena ( more bloat! )
• [ ] review secrets
• [ ] Better virtualisation module
• [ ] unstable pkgs as an overlay (pkgs.unstable)
• [ ] evaluation warning: profile: You have set either `nixpkgs.config` or `nixpkgs.overlays` while using `home-manager.useGlobalPkgs`. This will soon not be possible. Please remove all `nixpkgs` options when using `home-manager.useGlobalPkgs`.
• [ ] Home config system agnostic??
• [ ] https://github.com/nixified-ai/flake
• [ ] Use determinante.nix installer ( better warning/errors messages and more )

References

This configuration was inspired by and borrows from several excellent NixOS configurations:

• EmergentMind’s nix-config
• Edmund Miller’s dotfiles
• Remi Gelinas’ rosetta
• Isabel Roses’ dotfiles
• Montchr’s dotfield
• Henrik Lissner’s dotfiles
• MStream’s nix-chad
• Misterio77’s nix-config