DEV Community

David Foster
David Foster

Posted on • Edited on

A Dev-Ready NixOS Template for Daily Use

#nixos #nix #linux

Getting Started with NixOS: A Complete Template Guide

Introduction

NixOS is an amazing Linux distribution that offers unparalleled reproducibility and declarative system configuration. However, learning NixOS and writing all your customizations from scratch can be a daunting task. This guide presents a fully working NixOS template structure designed to help anyone interested in testing NixOS or getting started with their own configuration.

This template represents a snapshot mid-journey of a real-world migration to NixOS. It is a fully working setup that can be used as a daily driver immediately. The goal is to get you running quickly so you can focus on developing your own Nix configuration while having quick local files to reference.

What's Included?

This setup uses Flakes and Home Manager to provide a modern, reproducible NixOS configuration. The architecture is designed to handle multiple workstations by using a variable system that points to hardware configurations located in the ./hardware directory. You'll find templates for:

  • Basic laptop configurations
  • Desktop configurations
  • NVIDIA gaming desktop with controller support

Package Management

The template includes a comprehensive set of system packages found at nix_modules/pkgs.nix, which includes support for multiple desktop environments and developer tools. User-specific applications are managed through Flatpaks, located at nix_modules/flatpak.nix. This separation allows for better isolation of user applications.

Editor Support

The template includes setup for both Vim and Neovim. At this time, the configuration simply enables these programs and installs support for their native building tools such as LazyVim and Vundle.

Dotfiles Management

There are several dotfiles already written and located at ./home/home_modules. Additionally, there is a systemd service that can mount a path you declare as a variable during setup to your user's .config/ directory, bringing your dotfiles to life on the system. This service can be found at ./nix_modules/systemd_custom_dotfiles.nix.

To use this feature, place your dotfile repository at ~/.dotfiles/config and uncomment the systemd Nix file in the imports section of configuration-custom.nix. This is particularly useful for developing your Nix setup while using it as a daily driver, as it allows you to work on dotfiles that are WIPs or contain sensitive information in a separate repository.

Desktop Environments

The template comes pre-configured with support for multiple desktop environments:

  • GNOME
  • KDE Plasma
  • Hyprland
  • BSPWM (the author's favorite)

Note that the template does not include configurations for Hyprland or BSPWM—you'll need to bring your own. If you're interested in using the author's dotfiles for BSPWM or Hyprland (which are works in progress), they can be found on GitHub:

Quick Start Guide (TL;DR)

A fully working setup to begin your NixOS development. It'll get you running immediately so you can just focus on developing your own Nix configuration while running it with quick local files to reference.

Step-by-Step Setup

  1. Install NixOS from ISO

  2. Install temporary tools:

   nix-env -iA nixos.vim nixos.git
Enter fullscreen mode Exit fullscreen mode
  1. Clone the template repository: 
   git clone https://github.com/dfosterj/nixos-template /etc/nixos/nix
Enter fullscreen mode Exit fullscreen mode

  1. Backup and edit configuration.nix:

    • Make a backup of /etc/nixos/*.nix files
    • Edit configuration.nix by removing all configuration lines except boot.* configurations
    • Add the path to the flake directory to the imports section
    • See the GitHub README for more detailed explanation and examples

  2. Review hardware templates:

    • Review the hardware templates in the ./hardware directory
    • Create a new template or edit the matching workstation configuration

  3. Create host variables:

    • Run bash setup.sh to create the variable file /etc/nixos/host-variables.nix
    • Or manually create it (see GitHub README for example)

Important Setup Note: The workstation name must match with the corresponding common hardware file at ./hardware/workstationName-hardware-custom.nix

  1. Build and switch to the flake: 
   # Remove temporary packages
   nix-env -e vim
   nix-env -e git

   # Build and switch
   sudo nixos-rebuild switch --flake /etc/nixos/nix#default --impure
Enter fullscreen mode Exit fullscreen mode

Enjoy and start using Nix!

Using Personal Dotfiles During Development

If you want to use a personal dotfile repository while developing your Nix setup, you can copy your repository to ~/.dotfiles/config and uncomment the systemd_custom_dotfile.nix import in configuration-custom.nix. This process will link your files for live system use, allowing you to develop your Nix configuration while using your existing dotfiles.

Directory Structure

Here's a quick tree view of the template structure:

├── configuration.nix
├── hardware-configuration.nix
├── host-variables.nix
└── nix
├── configuration-custom.nix
├── flake.lock
├── flake.nix
├── hardware
    │   ├── laptop-hardware-custom.nix
    │   ├── desktop-hardware-custom.nix
    │   └── nvidia-desktop-hardware-custom.nix
├── home
    │   ├── desktop_files
    │   ├── dotfiles
    │   ├── flake.nix
    │   ├── home.nix
    │   └── home_modules
├── nix_modules
    │   ├── flatpak.nix
    │   ├── picom.nix
    │   ├── pkgs.nix
    │   ├── systemd_custom_dotfile.nix
    │   └── unstable.nix
├── README.md
└── setup.sh
Enter fullscreen mode Exit fullscreen mode

Understanding the Architecture

Configuration Files

  • configuration.nix: The main NixOS configuration file that should only contain boot-related configurations and imports
  • host-variables.nix: Contains workstation-specific variables (workstation name, user name, git information)
  • configuration-custom.nix: The main custom configuration that imports all modules

Hardware Configurations

The hardware/ directory contains workstation-specific hardware configurations. This separation allows you to:

  • Keep unique hardware and boot configurations outside the main repository
  • Protect sensitive information (like encryption keys)
  • Easily switch between different hardware profiles

Home Manager Integration

The home/ directory contains Home Manager configurations, including:

  • User-specific dotfiles
  • Desktop file configurations
  • Home Manager modules for various applications

Nix Modules

The nix_modules/ directory contains reusable Nix modules:

  • pkgs.nix: System-wide package definitions
  • flatpak.nix: Flatpak application definitions
  • systemd_custom_dotfile.nix: Systemd service for linking external dotfiles
  • unstable.nix: Unstable package channel configuration
  • picom.nix: Picom compositor configuration

Next Steps

Once you have the template running, you can:

  1. Customize the hardware configuration for your specific workstation
  2. Add or modify packages in nix_modules/pkgs.nix
  3. Configure your preferred desktop environment
  4. Set up your dotfiles using the provided systemd service or Home Manager
  5. Experiment with NixOS features and build your ideal system

Resources

This template is designed to lower the barrier to entry for NixOS while providing a solid foundation for building your own customized system. Happy Nix'ing!

Top comments (0)