nixos-config

NixOS Configuration Framework Documentation

Welcome to the documentation for this modern NixOS configuration framework featuring declarative system management with Wayland, sops-nix, and unified theming.

Quick Start

Prerequisites

• NixOS system with flakes enabled
• Basic familiarity with Nix
• Age encryption key for secrets

Installation

1. Clone this repository
2. Follow the Installation Guide for detailed steps
3. Apply configuration: nixos-rebuild switch --flake .#hostname

Key Commands

# Update system
just up

# Rebuild configuration
just switch

# Apply home-manager changes
just home       # Work mode (full dev setup)
just game       # Gaming mode (minimal + Steam)

# Maintenance
just cleanup    # Smart cleanup (keep 3 generations)

# Manage secrets
just encode    # Encrypt secrets
just decode    # Decrypt secrets

Documentation

Core Guides

• Installation Guide - Complete setup instructions
• Configuration Reference - Detailed configuration reference
• Program Configurations - Configured programs and settings
• Secrets Management - Managing encrypted secrets

Configuration Overview

This framework provides:

• Declarative System - Entire system defined in Nix
• Modern Desktop - Wayland with Niri compositor
• Unified Theming - Stylix for consistent appearance
• Secret Management - Encrypted configuration with sops-nix
• Development Ready - Pre-configured development environment
• Reproducible - Flakes ensure reproducible builds

Architecture

nixos-config/
├── docs/               # Documentation (you are here)
├── home/               # Home Manager configurations
│   ├── default.nix        # Work mode (full dev setup)
│   ├── gaming.nix         # Gaming mode (minimal + Steam)
│   └── programs/          # Program-specific configs
├── hosts/              # Host-specific settings
├── flake.nix          # Main configuration entrypoint
├── justfile          # Common tasks automation
└── secrets.enc.yaml  # Encrypted secrets

Key Features

Desktop Environment

• Display Protocol: Wayland for modern graphics
• Window Manager: Niri tiling compositor
• Terminal: Kitty/Foot with full Unicode support
• Editor: Helix with LSP integration
• Browser: Firefox with privacy settings

Development Stack

• Languages: Nix, Rust, Python, Go, JavaScript
• Tools: Git, Cargo, UV, Node.js
• LSP: Complete language server setup
• Version Control: Git with Delta diff viewer
• AI Assistant: Claude Code with custom commands/skills

System Management

• Package Management: Nix Flakes + Home Manager
• Security: sops-nix with AGE encryption
• Theming: Stylix unified theming
• Automation: Justfile for common tasks

Getting Help

Troubleshooting

• Check the Configuration Reference for common issues
• Review logs with journalctl -xe
• Test configurations with nix flake check

Community

• NixOS Discourse
• NixOS Wiki
• Home Manager Manual

Contributing

This configuration follows semantic versioning and conventional commits.

When contributing:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ using NixOS

This site is open source. Improve this page.