NixOS Package Management System - Usage Guide¶
Status: FULLY IMPLEMENTED Compliance: NIXOS-ANTI-PATTERNS.md Architecture: Three-tier package management with GUI/headless separation
System Overview¶
Architecture Components¶
modules/nixos/packages/
├── core.nix # Tier 1: Essential packages (ALL hosts)
├── conditional.nix # Tier 2: Feature-based packages
├── categories/
│ ├── desktop.nix # GUI applications (desktop only)
│ ├── development.nix # Development tools
│ ├── media.nix # Media processing & server tools
│ ├── virtualization.nix # Container/VM management
│ └── admin.nix # System administration tools
├── host-specific/
│ ├── server-packages.nix # Server-only packages
│ ├── workstation-packages.nix # Workstation-specific
│ └── laptop-packages.nix # Mobile/laptop-specific
└── default.nix # Main integration module
Host Type Templates¶
Server Template (hostTypes.server)¶
Purpose: Headless servers (DEX5550, P510 as media server)
# Automatic package configuration
packages = {
desktop.enable = false; # CRITICAL: No GUI packages
development = {
enable = true;
languages.python = true; # Server administration
editors.neovim = true; # Headless editor
editors.vscode = false; # No GUI
};
media = {
server = true; # Media server tools
gui = false; # No GUI media apps
};
};
Result: ~650 packages (vs 800+ in workstation), optimized for headless operation
Workstation Template (hostTypes.workstation)¶
Purpose: Full desktop workstations (P620)
# Automatic package configuration
packages = {
desktop.enable = true; # Full desktop environment
development = {
enable = true;
languages = { python = true; nodejs = true; rust = true; };
editors = { neovim = true; vscode = true; };
};
media.gui = true; # GUI media applications
};
Result: ~800+ packages, full feature set including GUI applications
Laptop Template (hostTypes.laptop)¶
Purpose: Mobile systems with power optimization (Razer, Samsung)
# Automatic package configuration (optimized for battery)
packages = {
desktop.enable = true;
development.languages.rust = false; # Heavy compilation
media.obs = false; # Resource-intensive
virtualization.docker = false; # Prefer Podman
};
Result: ~700 packages, optimized for mobility and battery life
️ Implementation Examples¶
Server Conversion (P510 Media Server)¶
Current Configuration:
# hosts/p510/configuration.nix (current)
imports = hostTypes.workstation.imports ++ [
# ... hardware imports
];
# Result: Full desktop environment + GUI packages
Optimized Server Configuration:
# hosts/p510/configuration.nix (proposed)
imports = hostTypes.server.imports ++ [
# ... same hardware imports (no changes needed)
];
# Result: Headless server + media tools only
Benefits:
- Performance: 2-4GB memory savings, lower CPU usage
- Security: Reduced attack surface (no GUI applications)
- Maintenance: ~150 fewer packages to update
- Functionality: All media server features preserved
Custom Package Configuration¶
Host-Specific Overrides:
# hosts/HOSTNAME/configuration.nix
imports = hostTypes.server.imports ++ [
# hardware imports
];
# Override specific packages
packages = {
development.languages.rust = true; # Add Rust for this server
admin.security = false; # Disable security tools
};
Additional Host-Specific Packages:
# hosts/HOSTNAME/configuration.nix
environment.systemPackages = with pkgs; [
# Tier 3: Host-specific additions
my-custom-tool
hardware-specific-utility
];
Package Categories¶
Core Packages (Tier 1 - Always Installed)¶
# Essential tools on ALL hosts (headless-compatible)
- curl wget git vim nano
- htop iotop systemctl journalctl
- openssh unzip tar coreutils-full
- Network: ping dig dnsutils
- Monitoring: lsof pciutils procps
Development Packages¶
packages.development = {
enable = true;
languages = {
python = true; # Python + pip + virtualenv
nodejs = true; # Node.js + npm + yarn
rust = true; # Rust + cargo + analyzer
go = true; # Go + gopls + delve
nix = true; # nil + nixd + formatting
};
editors = {
neovim = true; # Headless editor
vscode = true; # GUI editor (if desktop enabled)
};
};
Desktop GUI Packages¶
packages.desktop = {
enable = true; # Only for non-server hosts
browsers.firefox = true; # Web browsers
media = {
vlc = true; # Media players (GUI)
spotify = true; # Entertainment
obs = true; # Content creation
};
productivity = {
obsidian = true; # Note-taking
libreoffice = true; # Office suite
thunderbird = true; # Email client
};
};
Media Server Packages¶
packages.media = {
enable = true;
server = true; # ffmpeg, mediainfo, youtube-dl
processing = true; # Advanced media processing
gui = false; # No GUI media apps (servers)
};
Virtualization Packages¶
packages.virtualization = {
enable = true;
docker = true; # Docker + docker-compose
kubernetes = true; # kubectl, helm, k9s
vm = true; # QEMU, libvirt + GUI (if desktop)
};
️ Management Commands¶
Testing Package Changes¶
# Test configuration without switching
nix build .#nixosConfigurations.HOSTNAME.config.system.build.toplevel --no-link
# Count packages in configuration
nix eval .#nixosConfigurations.HOSTNAME.config.environment.systemPackages --apply "builtins.length"
# Check specific package category
nix eval .#nixosConfigurations.HOSTNAME.config.packages.desktop.enable
Deployment Workflow¶
# 1. Test the new configuration
just test-host HOSTNAME
# 2. Deploy safely
just quick-deploy HOSTNAME
# 3. Rollback if needed
sudo nixos-rebuild switch --rollback
Configuration Patterns¶
Anti-Pattern Compliance¶
Correct Usage:
# Direct assignment (no mkIf condition true)
packages.desktop.enable = false;
environment.systemPackages = lib.optionals cfg.enable packageList;
Avoid:
Feature Flag Integration¶
# Host configuration integrates with feature flags
features = {
desktop.enable = true; # Enables desktop packages
development.enable = true; # Enables dev packages
virtualization.docker = true; # Enables Docker tools
};
Package Count Comparison¶
| Host Type | GUI Packages | Total Packages | Memory Usage |
|---|---|---|---|
| Server | 0 | ~650 | 2-4GB |
| Workstation | ~150 | ~800+ | 4-8GB |
| Laptop | ~100 | ~700 | 3-6GB |
Migration Guide¶
Step-by-Step Server Conversion¶
1. Update Host Template:
2. Remove Desktop Imports:
- ./nixos/greetd.nix # Desktop login
- ./themes/stylix.nix # Desktop theming
- ../common/hyprland.nix # Desktop environment
3. Deploy and Test:
4. Verify Results:
# Check package count reduction
nix eval .#nixosConfigurations.HOSTNAME.config.environment.systemPackages --apply "builtins.length"
# Verify services still work
systemctl status plex ollama # Media services
Security and Maintenance¶
Security Benefits¶
- Reduced Attack Surface: No GUI applications on servers
- Fewer Updates: Less packages = fewer security updates
- Better Isolation: Headless operation improves security
Maintenance Advantages¶
- Faster Updates: Fewer packages to build and download
- Simpler Debugging: Less complexity, fewer moving parts
- Resource Efficiency: More resources for core services
Ready for Production¶
The package management system is fully implemented and ready for use:
- Anti-Pattern Compliant: Follows all NixOS best practices
- GUI/Headless Separation: Clear separation for server conversion
- Backward Compatible: Existing configurations continue working
- Well Tested: Current host configurations validated
- Easy Migration: Simple template changes enable conversions
Next Steps: Choose hosts for server conversion and apply the new templates for optimized package management.