nix-homelab

• nix-homelab
  • Features
    • Roles
    • User programs
    • TUI floating panel configuration
  • Documentation
    • Hosts
    • Network
    • Structure
  • Usage
    • Demo
      • Installation
      • Update
      • Re-use the demo
    • Secrets initialisation (AGE & SOPS)
    • Homelab initialisation
    • NixOS installation & update
      • Update from you local computer/laptop
    • Update roles or multiple hosts
  • Commands
• A big thanks ❤️

Features

This homelab entirelly managed by NixOS

All the configuration is stored on homelab.json file, you can do:

• Define network CIDR
• Define hosts
• Define the roles installed for selected hosts
• Define services descriptions
• etc ...

This documentation is generated from homelab.json file content

Roles

The main roles used in this home lab

This list generated with just doc-update command

Logo	Module	Hosts	Description
	wireguard	router-living, badphone	An VPN client/server alternative to IPSec and OpenVPN
	acme	rpi40, bootstore	Let's Encrypt Automatic Certificate Management Environment
	coredns	rpi40	A Go DNS server, it used for serving local hosts and alias
	ntp	rpi40, bootstore, srvhoma	Network Time Protocol
	mosquitto	rpi40	A mqtt broker [service port 1883]
	zigbee2mqtt	rpi40	A zigbee2mqtt [service port 8080]
	adguard	bootstore	DNS ad blocker [service port 3002]
	dashy	bootstore	The Ultimate Homepage for your Homelab [service port 8081]
	grafana	bootstore	The open and composable observability and data visualization platform [service port 3000]
	loki	bootstore	Scalable log aggregation system [service port 8084,9095]
	nfs	bootstore	A Linux NFS server, it used for backuping a servers and Latops
	nix-serve	bootstore	For caching the nix build results
	prometheus	bootstore	Monitoring system and time series database [service port 9090]
	smokeping	bootstore	Latency measurement tool
	statping	bootstore	A Status Page for monitoring your websites and applications with beautiful graphs [service port 8082]
	uptime	bootstore	A Status Page [service port 3001/8083]
	home-assistant	bootstore	Open source home automation [service port 8123]

User programs

Logo	Name	Description
	Firefox	Browser
	Gimp	Raster graphics editor
	i3	Tiling window manager
	Inkscape	Vectorial graphics editor
	Libreoffice	Office editor
	Meld	Awesome diff tool
	Navi	interactive cheatsheet tool
	Neovim	VIDE (badele's customized nix neovim

TUI floating panel configuration

Bluetooth (bluetuith)	Disk (bashmount)
Mixer (pulsemixer)	Network (nmtui)
Process (pulsemixer)

Documentation

Hosts

List of hosts composing the home lab

This list generated with just doc-update command

Logo	Name	OS	Description
	box (192.168.0.1)	Sagem	SFR internet box
	router-living (192.168.254.254)	MikroTik	Livingroom mikrotik router
	router-ladbedroom (192.168.254.253)	MikroTik	Bedroom mikrotik router
	router-homeoffice (192.168.254.252)	MikroTik	Office mikrotik router
	sadhome (192.168.254.200)	NixOS	Stephanie's laptop
	rpi40 (192.168.254.101)	NixOS	The RPI 4 server
	bootstore (192.168.254.100)	NixOS	HP Microserver N40L server
	badphone (192.168.254.194)	Android	Bruno's phone
	ladphone (192.168.254.184)	Android	Lucas's phone
	sadphone (192.168.254.188)	Android	Steph's phone
	loadphone (192.168.254.199)	Iphone	Lou's phone
	tv-chromecast (192.168.254.105)	Chromecast	TV Chromecast
	bedroom-googlemini-A (192.168.254.197)	GoogleMini	Google Mini room A
	bedroom-googlemini-C (192.168.254.196)	GoogleMini	Google Mini room C
	b4d14 (192.168.254.124)	NixOS	Dell XPS 9560 Latop
	badxps (192.168.254.114)	NixOS	Dell XPS 9570 Latop
	badxps-eth (192.168.254.179)	NixOS	Dell XPS 9570 Latop
	bridge-hue (192.168.254.191)	Bridge	Philips Hue bridge
	srvhoma (192.168.254.116)	NixOS	First NUC homelab server
	vm-test (127.0.0.1)	NixOS	qemu VM (SSH on port 2222)

Network

generated by diagrams ./docs/network_architecture.py
generated by plantuml ./docs/network.puml

Structure

• Configuration
  • homelab.json: main homelab file configuration (roles servers, network, etc)
  • hosts: hosts configuration (system, hardware, host secrets)
    • *.nix: user accounts
  • users: users configuration (on user environment, user secrets)
• System
  • nix: all *.nix files
    • home-manager: All users *.nix files (installed on user environment)
    • modules: all nix modules
      • home-manager: user modules
      • nixos: nixos modules (installed on system wide)
        • host.nix: host options (custom options for host)
    • nixos: all *.nix files installed on system wide
    • overlays: overlays nix derivations
    • pkgs: custom nix packages

Usage

Demo

To test nix-homelab as well as the configuration of a workstation, nix-homelab offers a demo that runs on a virtual machine based on QEMU.

Installation

• From your desktop
  • nix develop
  • just iso-build
  • just demo-qemu-nixos-install (demopass password) Go for a walk or have a coffee
  • when the installation is completed, reboot the virtual machine (you can write reboot on the terminal) and select Firmware Setup => Boot Manager => UEFI QEMU HardDisk

Update

You can update from your remote desktop or directly from your recent installed desktop

• From remote

  • just demo-qemu-nixos-update

• From your fresh installation

  • ssh root@localhost -p 2222 (demopass password)
  • ghq clone https://github.com/badele/nix-homelab.git
  • cd ghq/github.com/badele/nix-homelab
  • just nixos-update

Re-use the demo

just demo-start

Secrets initialisation (AGE & SOPS)

Your pass (passwordstore) configuration must be correctly configured.

In order to be able to encrypt your credentials, you first need initialize an age key. It is this key that will subsequently have to be added in the .sops.yaml file

• age-keygen | pass insert -m nix-homelab/users/your_username
• pass show nix-homelab/users/your_username | grep AGE-SECRET-KEY >> ~/.config/sops/age/keys.txt

### NixOS installation & update

See [Commons installation](docs//installation.md)

#### Update from you local computer/laptop

- From your fresh installation
  - `ghq clone https://github.com/badele/nix-homelab.git`
  - `cd ghq/github.com/badele/nix-homelab`
  - `just nixos-update`

Commands

Home lab commands list

This list generated with just doc-update command

Available recipes:
    help                                              Help it showed if just is called without arguments
    precommit-install                                 Setup pre-commit
    precommit-update                                  Update pre-commit
    precommit-check                                   precommit check
    doc-update FAKEFILENAME                           Update documentation
    lint                                              Lint the project
    debug-repl                                        Repl the project
    flake-metadata                                    Show flake metadata
    flake-update                                      Update the flake
    flake-check                                       Check the nix homelab configuration
    passwd-generate                                   Generate random password
    secret-update FILE                                Update secrets SOPS
    nixos-init-host host                              Init nixos host if not exists
    nixos-install hostname targetip port="22"         Install new <hostname> to <target>:<port> system wide
    nixos-garbage                                     Nixos clean build cache and garbage unused derivations
    nixos-build hostname="" options=""                Nixos build local host
    demo-nixos-install hostname targetip port="22"    Install new <hostname> to <target>:<port> system wide
    nixos-update hostname="" options=""               Update NixOS on local host
    nixos-remote-deploy hostname targetip             Deploy NixOS on remote host
    home-build                                        Home build for local user
    home-deploy                                       Home deploy local user
    iso-build                                         Build NixOS ISO image
    demo-init-credentials passwd="demopass"           Init demo credentials
    demo-start                                        Start NixOS demo from ISO image
    demo-qemu-nixos-install                           Test NixOS installation deployment on qemu virutal machine
    demo-qemu-nixos-update                            Test NixOS update deployment on qemu virutal machine
    demo-stop                                         Stop demo vm test
    demo-clean                                        Clean demo vm test
    packages                                          Show installed packages

A big thanks ❤️

A big thank to the contributors of OpenSource projects in particular :

• doctor-cluster-config from German TUM School of Computation
• Mic92 and for his some nix contributions
• Misterio77 and for his some nix contributions
• longerHV nix configuration file
• wikipedia for logos inventories