The Only NixOS Config Your Homelab Needs

If you run a homelab, you know the drill. You’re constantly tweaking configs, managing services, and trying to keep everything reproducible. It’s fun, but it can also become a mess of scattered files and manual steps. What if you could define your entire lab—services, networking, users, and secrets—in one clean, declarative configuration?

That’s the idea behind chenglab, a NixOS configuration framework that promises to be the only config your homelab needs. It’s not just another set of examples; it’s a structured, opinionated foundation to build on.

What It Does

Chenglab is a Nix Flake-based configuration for NixOS systems, specifically tailored for homelab environments. It provides a modular structure to define your machines, the services running on them, user accounts, and even secrets management. Instead of writing a NixOS config from scratch, you fill in the blanks in a well-organized template.

Think of it as a starter kit that enforces good practices: everything is defined in code, secrets are handled with sops-nix, and service configuration is kept separate from machine definitions. It comes pre-configured with common homelab services like Caddy, Tailscale, and Docker, so you can get useful things running quickly.

Why It’s Cool

The real value here is in the structure and the choices. The author has already made a bunch of sensible decisions that you’d otherwise spend hours researching.

Modular by Design: The config separates concerns. You define your machines (physical or virtual systems), your services (like a web server or VPN), and your users in different modules. This makes it easy to see what’s running where and to reuse service configs across machines.

Secrets Built-In: It integrates sops-nix from the start. You can store encrypted secrets (API keys, passwords) right in your Git repo and have them automatically decrypted on your target machines. No more .env files scattered around or manual copying.

It’s a Flake: The entire setup is a Nix Flake, which means it’s reproducible and has explicit dependencies. Running nix flake update can bump all your inputs in one go. It embraces the modern Nix tooling.

Realistic Defaults: It includes configs for things you almost certainly need: an SSH server, Tailscale for secure remote access, and Caddy for easy reverse proxying with automatic HTTPS. It’s a homelab config made by someone who actually runs a homelab.

How to Try It

The quickest way to get started is to use the repository as a template.

1. Clone and explore:

   git clone https://github.com/eh8/chenglab
   cd chenglab
   

   Look through the directory structure. The key areas are machines/, services/, and users/.

2. Adapt it for your lab: You’ll want to:

   • Edit machines/ to define your own systems (e.g., truenas.nix, k8s-node.nix).
   • Replace the example user in users/.
   • Set up sops-nix with your age key to manage secrets.
   • Adjust the included services in services/ to your liking.

3. Build and deploy: Use the standard NixOS commands to build your configuration or deploy it to a remote machine. The flake.nix file defines the outputs.

This isn’t a one-click install; it’s a foundation. You’re expected to read the code and customize it. That’s the point—it’s your config, just with a huge head start.

Final Thoughts

Chenglab is the kind of project that makes you nod and think, "Yeah, that’s how I’d want to structure mine." It’s a fantastic reference and a practical starting point, especially if you’re past the basics of NixOS but don’t want to architect a large-scale config from zero.

If you’ve been meaning to move your homelab to NixOS or refactor a growing pile of Nix files, this repo is worth a long look. Fork it, break it, and mold it into the declarative definition of your own lab. It might just become the only NixOS configuration you need.

Found an interesting project? Share it with us @githubprojects.