Advanced NixOS Features

This document describes the expert-level features implemented in this NixOS template, designed for production-grade deployments and advanced users.

Overview

The template now includes several advanced modules that provide enterprise-grade functionality:

Features

Hardware Detection (modules.hardware.detection)

Automatically detects and optimizes for your hardware configuration:

modules.hardware.detection = {
  enable = true;
  autoOptimize = true;  # Apply hardware-specific optimizations
  profile = null;       # Auto-detect: "minimal", "balanced", "high-performance"

  reporting = {
    enable = true;
    logLevel = "info";
  };
};

Detects:

Optimizes:

Performance Monitoring (modules.services.monitoring)

Enterprise-grade monitoring with Prometheus ecosystem:

modules.services.monitoring = {
  enable = true;

  prometheus = {
    enable = true;
    retention = "30d";
    alerting.enable = true;
  };

  exporters = {
    node.enable = true;      # System metrics
    systemd.enable = true;   # Service metrics
    process.enable = true;   # Process metrics
    blackbox.enable = true;  # Network probes
  };

  grafana = {
    enable = true;
    port = 3000;
  };

  systemHealth = {
    enable = true;
    checks = [
      "disk-space"
      "memory-usage"
      "cpu-temperature"
      "service-status"
      "network-connectivity"
    ];
  };
};

Includes:

Nix Optimization (modules.core.nixOptimization)

Advanced Nix store and build optimization:

modules.core.nixOptimization = {
  enable = true;

  tmpfs = {
    enable = true;
    size = "50%";  # Use 50% of RAM for /tmp
  };

  store = {
    autoOptimise = true;
    gc = {
      automatic = true;
      dates = "weekly";
      options = "--delete-older-than 14d";
    };
  };

  performance = {
    maxJobs = "auto";
    cores = 0;  # Use all cores
    keepOutputs = true;
    keepDerivations = true;
    useCgroups = true;
  };
};

Features:

🔐 Secrets Management (SOPS-nix Integration)

Secure configuration management with age encryption:

# In your configuration
sops = {
  defaultSopsFile = ./secrets/secrets.yaml;
  age.keyFile = "/var/lib/sops-nix/key.txt";

  secrets = {
    "database/password" = {
      owner = "postgres";
      group = "postgres";
    };
    "api/secret-key" = {
      owner = "webapp";
      mode = "0400";
    };
  };
};

🧪 Comprehensive Testing

VM-based integration testing with multiple test scenarios:

# Run all tests
nix flake check

# Run specific VM tests
nix build .#checks.x86_64-linux.vm-test-desktop
nix build .#checks.x86_64-linux.vm-test-server

# Lint and formatting gates
nix build .#checks.x86_64-linux.statix-check
nix build .#checks.x86_64-linux.deadnix-check
nix build .#checks.x86_64-linux.shellcheck-check
nix build .#checks.x86_64-linux.treefmt

# Real builds of the WSL2 system and its Home Manager generation
nix build .#checks.x86_64-linux.wsl2-config
nix build .#checks.x86_64-linux.wsl2-home

The full list is nix flake show. Every host in nixosConfigurations is evaluated by nix flake check itself, so there is no separate “configuration syntax” check — an unevaluatable host fails the check directly.

Test Categories:

Advanced Module Template

Production-ready module development pattern with comprehensive validation:

modules.template = {
  enable = true;

  services = {
    web-api = {
      name = "web-api";
      port = 8080;
      enable = true;
    };
  };

  networking = {
    allowedIPs = [ "127.0.0.1" "192.168.1.0/24" ];
  };

  resources = {
    memory = "2G";
    cpu = "50%";
  };

  features = {
    metrics = true;
    healthCheck = true;
  };
};

Features:

Flake Enhancements

Advanced Caching

The flake now includes optimized caching configuration:

nixConfig = {
  extra-substituters = [
    "https://cache.nixos.org"
    "https://nix-community.cachix.org"
    "https://devenv.cachix.org"
  ];
  max-jobs = "auto";
  cores = 0;
  auto-optimise-store = true;
  experimental-features = [
    "nix-command"
    "flakes"
    "ca-derivations"
    "recursive-nix"
  ];
};

Testing Infrastructure

Comprehensive test suite with multiple validation levels:

Usage Examples

Basic Setup

Enable core optimizations in any configuration:

{
  imports = [ ./path/to/template ];

  modules = {
    core.nixOptimization.enable = true;
    hardware.detection.enable = true;
  };
}

Production Server

Full monitoring and optimization for production:

{
  modules = {
    core.nixOptimization.enable = true;
    hardware.detection.enable = true;
    services.monitoring = {
      enable = true;
      grafana.enable = true;
      systemHealth.enable = true;
    };
  };
}

Development Workstation

High-performance development environment:

{
  modules = {
    core.nixOptimization = {
      enable = true;
      performance.maxJobs = "auto";
      store.gc.dates = "daily";
    };

    hardware.detection = {
      enable = true;
      profile = "high-performance";
    };

    services.monitoring.enable = true;
  };
}

Performance Profiles

The system automatically detects and applies performance profiles:

High Performance

Balanced

Resource Constrained

Minimal

Best Practices

Security

Performance

Reliability

Development

Troubleshooting

Common Issues

Hardware Detection Not Working

# Check detection service
journalctl -u hardware-detection

# Manual detection
nix-shell -p dmidecode lshw --run "lshw -short"

Monitoring Services Failing

# Check Prometheus
systemctl status prometheus
journalctl -u prometheus

# Check exporters
systemctl status prometheus-node-exporter
curl localhost:9100/metrics

Build Performance Issues

# Check Nix settings
nix show-config | grep -E "(max-jobs|cores)"

# Monitor build resources
htop # During builds

Debug Mode

Enable debug logging for detailed information:

modules = {
  hardware.detection.reporting.logLevel = "debug";
  services.monitoring.prometheus.extraFlags = [ "--log.level=debug" ];
};

Migration Guide

From Basic Template

  1. Update your flake inputs to include sops-nix
  2. Import new modules in your configuration
  3. Enable desired features gradually
  4. Test in VM before deploying to production

From Existing NixOS

  1. Backup current configuration
  2. Import template modules
  3. Migrate existing settings to new module structure
  4. Test thoroughly in development environment
  5. Deploy with rollback capability

Contributing

When adding new features:

  1. Follow the module template pattern
  2. Include comprehensive validation
  3. Add appropriate tests
  4. Document configuration options
  5. Update this documentation

Support

For issues and questions:

  1. Check the troubleshooting section
  2. Review module documentation
  3. Test in isolated VM environment
  4. Create detailed issue reports with system information

This template represents production-grade NixOS patterns and should be thoroughly tested before production deployment.