Skip to content
thatbaguPublic

About

Template of my personal nix homelab

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

234 Commits

Folders and files

Repository files navigation

nixlab

License Badge Latest Release Badge Checks Passing Badge

A NixOS and k3s platform for running services on your own hardware.

Getting Started • Documentation • Why nixlab • Quick Start

nixlab is a self-hosting platform built on NixOS and k3s. One tested flake gives you a cluster, or a single machine, with HTTPS for every app, DNS, a VPN, replicated storage, backups, monitoring and a NAS, all derived from one configuration file. Your repo holds only that configuration; nixlab is a dependency you upgrade by changing its version. It runs a homelab, a small office or a single Raspberry Pi the same way.

How It Works

Describe your machines and services in vars.nix:

{
  domain = "home.example.com";

  nodes = {
    mymaster = { hostname = "mymaster"; master = true; disk = "/dev/nvme0n1"; tags = [ "homelab" "master" ]; };
    myworker = { hostname = "myworker"; master = false; disk = "/dev/sda"; tags = [ "homelab" "worker" ]; };
  };

  backups.enable = true;
  monitoring.enable = true;
}

Install each node over SSH, from any machine:

nix run .#install -- mymaster root@192.168.1.20

Add your apps, one file each in apps/:

{ nixlab, ... }:

nixlab.webApp {
  name = "uptime-kuma";
  image = "docker.io/louislam/uptime-kuma:1.23.16";
  port = 3001;
  host = "status.${nixlab.vars.domain}";
  storage."/app/data" = "2Gi";
}

Push to GitHub. CI renders the Kubernetes manifests with nixidy, Argo CD deploys them, and every app is at https://<app>.home.example.com with a certificate, a DNS name and backups.

Why nixlab

One file. Machines, network, apps and users, all in vars.nix.

Nodes in one command. Install, replace or reinstall a node over SSH.

HTTPS everywhere. Every app gets a name, a certificate and backups.

Survives failure. In a cluster, apps outlive a dead node; power cuts shut down cleanly.

Your phone knows first. Alerts for failing disks, backups and certificates.

Checked before it ships. CI builds every node and renders every manifest.

Every boot starts clean. Nodes are rebuilt from config, so nothing drifts.

Pinned and tested. Every input pinned; each update tested alone in VM tests.

Upgrade with one line. nixlab is a dependency, not a template you fork.

Portable. The whole system lives in git; rebuild it on any machines, x86 or ARM.

How it works under the hood →

Quick Start

Without Nix

On your laptop (Linux or macOS):

curl -fsSLO https://raw.githubusercontent.com/thatbagu/nixlab/main/tools/nixlab.sh
sh nixlab.sh new myinfra && cd myinfra
sh ../nixlab.sh init                                  # keys and secrets
$EDITOR vars.nix                                      # your domain, nodes, network
sh ../nixlab.sh install mynode root@192.168.1.20      # boot the machine from any Linux USB first

With Flakes

nix flake init -t github:thatbagu/nixlab
nix run .#init                                        # keys and secrets
$EDITOR vars.nix                                      # your domain, nodes, network
nix run .#install -- mynode root@192.168.1.20         # boot the machine from any Linux USB first

Push the repo to GitHub, and Argo CD deploys the rest. template/ shows what the repo looks like; the Getting Started guide walks through every step.

Documentation

Comparison

nixlab Umbrel Unraid TrueNAS cluster-template
License 🟢 MIT 🟡 Noncommercial, source-available 🔴 Proprietary, paid 🟢 Open source 🟢 MIT
Configured through 🟢 One Nix file, in git 🟡 Web UI 🟡 Web UI 🟡 Web UI 🟢 A config file, rendered once into your repo
Machines 🟢 One, or a cluster with HA 🔴 One 🔴 One 🔴 One 🟢 A cluster
Rebuild a machine 🟢 One command, the same system every time 🟡 Reinstall, restore your data 🟡 Reinstall, restore your settings 🟡 Reinstall, upload a config backup 🟢 Re-apply its Talos config
The OS between boots 🟢 Wiped and rebuilt from config 🟡 Kept 🟡 Kept 🟡 Kept 🟢 Immutable (Talos)
Updates 🟢 Each tested alone in VM tests, merged when it passes 🟡 Vendor releases 🟡 Vendor releases 🟡 Vendor releases 🟡 Renovate pull requests
Upgrading the platform 🟢 nix flake update nixlab 🟢 Over the air 🟢 Over the air 🟢 Over the air 🔴 Merge upstream changes by hand
Moving to new hardware 🟢 Rebuild from git, then restore data from backups 🟢 Restore a backup during setup 🟡 Restore the boot-drive backup, plus a plugin for app data 🟡 Upload a config backup, then replicate pools 🟡 Re-apply from git; data only if you set up VolSync
Apps 🟢 Any container or Helm chart, one Nix file each 🟢 App store 🟢 Community apps, VMs 🟢 App catalog, VMs 🟢 Any Helm chart, as YAML

Want a web UI, an app store or VMs? Umbrel, Unraid and TrueNAS are easier. nixlab is for when you want every machine and app described in git, checked before it deploys, and rebuilt the same way every time.

Contributing

Bug reports, ideas and pull requests are welcome in Issues. See CONTRIBUTING.md for how the repo is laid out and how to run the tests.

Acknowledgments

License

MIT

About

Template of my personal nix homelab

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages