NixOS Template Setup Guide

This NixOS template includes comprehensive setup scripts to help new users get up and running quickly with a fully configured NixOS system.

Quick Start

For new NixOS users who want a guided setup experience:

# 1. Clone the template
git clone <your-template-repo> my-nixos-config
cd my-nixos-config

# 2. Run prerequisite checks
./scripts/check-prerequisites.sh

# 3. Choose your setup method:

# Option A: Quick setup with smart defaults
./scripts/quick-setup.sh

# Option B: Full interactive setup
./scripts/nixos-setup.sh

Setup Scripts Overview

1. Prerequisites Checker (check-prerequisites.sh)

Validates your system before attempting configuration:

Usage

./scripts/check-prerequisites.sh

What it checks

2. Quick Setup (quick-setup.sh)

Minimal interaction setup with sensible defaults:

Best for

Features

3. Full Interactive Setup (nixos-setup.sh)

Comprehensive guided setup with full customization:

Best suited for

Key Features

4. VM Detection (detect-vm.sh)

Specialized script for virtual machine environments:

Supported Platforms

Step-by-Step Setup Process

For New NixOS Installations

  1. Boot NixOS Live ISO
    • Download latest NixOS ISO
    • Boot from USB/DVD
    • Connect to internet

  2. Partition and Format Disks

    # Example for UEFI systems
sudo parted /dev/sda -- mklabel gpt
sudo parted /dev/sda -- mkpart root ext4 512MB 100%
sudo parted /dev/sda -- mkpart ESP fat32 1MB 512MB
sudo parted /dev/sda -- set 2 esp on

sudo mkfs.ext4 -L nixos /dev/sda1
sudo mkfs.fat -F 32 -n boot /dev/sda2

sudo mount /dev/disk/by-label/nixos /mnt
sudo mkdir -p /mnt/boot
sudo mount /dev/disk/by-label/boot /mnt/boot

  3. Setup Template

    cd /mnt
sudo git clone <your-repo> nixos-config
cd nixos-config
sudo ./scripts/check-prerequisites.sh
sudo ./scripts/nixos-setup.sh

  4. Install NixOS

    # The setup script will guide you through installation
# It will handle nixos-install automatically

For Existing NixOS Systems

  1. Clone Template

    git clone <your-repo> ~/.config/nixos-template
cd ~/.config/nixos-template

  2. Check Prerequisites

    ./scripts/check-prerequisites.sh

  3. Run Setup

    # Quick setup
./scripts/quick-setup.sh

# Or full setup
./scripts/nixos-setup.sh

  4. Apply Configuration

    # Generated configuration will be tested and applied automatically
# Or manually apply later:
sudo nixos-rebuild switch --flake .#your-hostname

Configuration Templates

User Templates

The template system provides pre-configured user environments:

Basic (user)

Developer (developer)

Gamer (gamer)

Minimal (minimal)

Server (server)

Desktop Environments

GNOME

Hyprland

niri

Niri

Advanced Features

Virtual Machine Optimization

The template automatically detects and optimizes for VM environments:

Secrets Management

Integrated agenix support for secure secret management:

Container Support

Built-in containerization with Podman:

Gaming Optimizations

When gaming template is selected:

Troubleshooting

Common Issues

Script Permission Denied

chmod +x scripts/*.sh

Prerequisites Check Fails

Configuration Build Fails

VM Detection Issues

# Manual VM detection
systemd-detect-virt
cat /sys/class/dmi/id/product_name

Network Configuration Problems

Getting Help

  1. Check Logs

    journalctl -xeu nixos-rebuild

  2. Validate Configuration

    just validate
nixos-rebuild dry-run --flake .#hostname

  3. Test Without Applying

    just test hostname

  4. Restore Previous Generation

    sudo nixos-rebuild switch --rollback

Manual Configuration

If automated setup doesn’t meet your needs:

  1. Copy Example Configuration

    # Starting points: desktop-template, laptop-template,
# server-template, wsl2-template
cp -r hosts/desktop-template hosts/my-host
  2. Customize Configuration
    • Edit hosts/my-host/configuration.nix
    • Update hosts/my-host/home.nix
    • Generate hardware config: sudo nixos-generate-config --show-hardware-config > hosts/my-host/hardware-configuration.nix

  3. Add to Flake

    Open flake.nix, find the ADD YOUR OWN HOSTS HERE block inside nixosConfigurations, and add an entry:

    my-host = flakeUtils.mkSystem {
  hostname = "my-host";      # must match the hosts/ directory name
  profile = "workstation";   # workstation, server, laptop, gaming,
};                           # development or minimal

    Use mkSystem rather than calling nixpkgs.lib.nixosSystem yourself — it wires in Home Manager, agenix and the flake metadata module for you. See HOST-TEMPLATES.md.

  4. Build and Switch

    just switch my-host

Next Steps

After successful setup:

  1. Customize Your Configuration
    • Explore hosts/your-hostname/ directory
    • Modify applications and settings
    • Add custom modules
  2. Learn NixOS

  3. Keep Updated

    just update        # Update flake inputs
just switch        # Apply updates
  4. Backup Your Configuration
    • Commit changes to git
    • Consider hosting on GitHub/GitLab
    • Document custom modifications

This setup system makes NixOS accessible to new users while providing the flexibility and power that experienced users expect.