Skip to main content

​
Quick Start Guide

This guide will help you get the homelab infrastructure up and running quickly.

​
Prerequisites

Before you begin, ensure you have:
1

Install Nix with Flakes

Install Nix with Flakes support enabled:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
The Determinate Nix installer automatically enables Flakes and provides a better installation experience.
2

Clone the Repository

Clone your homelab repository:
git clone https://github.com/soriphoono/homelab.git ~/homelab
cd ~/homelab
3

Set Up Development Environment (Optional)

Install direnv for automatic shell activation:
nix profile install nixpkgs#direnv
direnv allow
Or manually enter the development shell:
nix develop
The dev shell includes all necessary tools: colmena, agenix, sops, age, and more.

​
Validate the Configuration

Before deploying, always validate your flake: 
nix flake check
This command checks all NixOS systems, Home Manager configurations, and Nix-on-Droid setups for evaluation errors.
The flake check runs multiple validation passes:
  • System evaluation checks for all NixOS configurations
  • Home Manager activation package builds
  • Nix-on-Droid configuration validation
  • Pre-commit hooks and formatting checks

​
Deploy Your First System

1

Choose Your Configuration Type

Decide which type of configuration you’re deploying:
  • NixOS System - Full operating system configuration
  • Home Manager - User environment and dotfiles (standalone)
  • Nix-on-Droid - Android/Termux environment
2

Deploy a NixOS System

For deploying to a NixOS machine:
# Local deployment
sudo nixos-rebuild switch --flake .#hostname

# Example: Deploy the 'zephyrus' laptop configuration
sudo nixos-rebuild switch --flake .#zephyrus
The hostname must match a directory name in systems/. The flake automatically discovers all systems.
Available system configurations:
  • zephyrus - ASUS ROG Zephyrus laptop with hybrid AMD/NVIDIA graphics
  • lg-laptop - LG Gram laptop configuration
  • moonlight - Server configuration
  • docker-node - Containerized deployment
3

Deploy Home Manager Configuration

For deploying user environment on any system:
# Deploy standalone home configuration
home-manager switch --flake .#username

# Example: Deploy 'soriphoono' user configuration
home-manager switch --flake .#soriphoono
Home Manager configurations bound to specific hosts (e.g., user@hostname) are automatically deployed with the NixOS system and should not be deployed standalone.
4

Deploy to Android Device

For Nix-on-Droid on Android/Termux:
# On your Android device in Termux
nix-on-droid switch --flake .#soriphoono
Make sure you have Termux and Nix-on-Droid installed from F-Droid first.

​
Understanding Home Manager Patterns

The homelab uses a sophisticated naming pattern for Home Manager configurations:

Base Configuration

Pattern: homes/username/Base user configuration used everywhere. Example: homes/soriphoono/

Global Override

Pattern: homes/username@global/Supplementary config for standalone installs. Combined with base and exported as homeConfigurations.username.

Host-Specific

Pattern: homes/username@hostname/Machine-specific overrides automatically imported by NixOS. Example: homes/soriphoono@zephyrus/

​
Example: Adding a New System

1

Create System Directory

Create a new directory in systems/:
mkdir -p systems/my-server
2

Create Configuration

Create systems/my-server/default.nix:
{ pkgs, ... }: {
  # System-level configuration
  core = {
    boot.enable = true;
    hardware.enable = true;
    
    networking.network-manager.enable = true;
    
    users.myuser = {
      admin = true;
      shell = pkgs.fish;
      publicKey = "ssh-ed25519 AAAA...";
    };
  };
}
3

Add System Metadata (Optional)

Create systems/my-server/meta.json for architecture specification:
{
  "system": "x86_64-linux"
}
If omitted, defaults to x86_64-linux.
4

Deploy

The new system is automatically discovered:
nix flake check  # Validate first
sudo nixos-rebuild switch --flake .#my-server

​
Common Operations

​
Update Flake Inputs

Update all dependencies: 
nix flake update
Update specific input: 
nix flake lock --update-input nixpkgs-weekly

​
Check for Vulnerabilities

nix run .#check
This runs vulnix security audit and full flake validation.

​
Format Code

nix fmt
Automatically formats all Nix files using treefmt.

​
Next Steps

Architecture Overview

Learn about the flake structure and module organization

Module Configuration

Explore available modules in modules/nixos/, modules/home/, and modules/droid/
Pro tip: Use nix flake show to see all available configurations in your flake.

Build docs developers (and LLMs) love

Get started for freeTalk to us