Antoine Moran — Blog

Organising my NixOS config with den

2026-10-30T12:00:00Z

In my last post I explained why I use NixOS on my laptop and my servers. This one is about how the config itself is organised. It's managed with den, and I think it's a really nice way to structure a NixOS config once you have more than one machine.

The problem

A common way to organise a NixOS config is one folder per machine, each with its own configuration.nix that imports shared modules. That works, but it gets messy when one feature needs to touch several parts of the system.

For example, when I add a web service to my server, I need:

the service itself, often a container;
a route in Traefik, my reverse proxy, sometimes restricted to my VPN or behind single sign-on;
sometimes a firewall rule;
an uptime check in Gatus, my monitoring tool;
a tile on my Homepage dashboard.

With a config organised by machine, these things end up in different files, and when you remove the service you have to remember to clean up all of them. With den, everything about the service is in one place.

Aspects

den is based on the "dendritic" pattern. Every .nix file in my modules/ folder is a flake-parts module, and import-tree loads all of them automatically, so I never have to maintain a list of imports. Files whose name starts with _, like _hardware.nix, are skipped.

On top of that, den adds aspects. An aspect is a named piece of configuration. It can contain NixOS options, Home Manager options, and a list of other aspects to include. Machines and users are declared separately, and a machine is basically the list of aspects it uses. This is gila, my monitoring server, a bit shortened:

den.hosts.x86_64-linux.gila.users.antoine = {};

den.aspects.gila.includes = [
  den.aspects.shell
  den.aspects.common
  den.aspects.nix
  den.aspects.sops
  den.aspects.traefik
  den.aspects.gatus-public
  den.aspects.ntfy
  den.aspects.beszel-agent
];

My main server has the same kind of list, just longer (59 entries). To see what runs on a machine, I only need to read that list.

Reusable aspects

Aspects can also be functions that take arguments. den calls these "batteries", and you can write your own under den.provides, then use them as den._.<name>.

The one I use the most is called proxied-service. You give it a subdomain and a port, plus a few options, and it creates the Traefik route, the VPN restriction if needed, the single sign-on with Kanidm if needed, the Gatus check and the Homepage entry. With it, my whole Vaultwarden config looks like this:

den.aspects.vaultwarden = {
  includes = [
    (den._.proxied-service {
      subdomain = "bit";
      port = 8222;
      vpnOnly = true;
      monitorName = "Vaultwarden";
      homepage.group = "Small Icons";
    })
  ];

  nixos = {config, ...}: {
    sops.secrets.vaultwarden_token = { /* … */ };
    services.vaultwarden = {
      enable = true;
      environmentFile = config.sops.secrets.vaultwarden_token.path;
      config.ROCKET_PORT = 8222;
    };
  };
};

41 of my aspects use proxied-service. I also have one for containers, media-container, which sets the usual user and timezone variables, the shared Podman network and the secrets file. If I want to change how all my services are exposed, I only change one file.

Aspects that send data to each other

You might have noticed that the Vaultwarden aspect never mentions Gatus or Homepage, but it still appears in both. This works with what den calls quirks. A quirk is like a named list that any aspect can add to, and that another aspect can read. I declare mine once:

den.quirks.gatus-endpoint.description = "Gatus monitoring endpoint contributions from service aspects.";
den.quirks.homepage-entry.description = "Homepage dashboard entry contributions from service aspects.";
den.quirks.firewall-port.description  = "Firewall port contributions from service aspects.";

A service adds an entry (here through proxied-service):

gatus-endpoint = {
  name = "Vaultwarden";
  url = "http://127.0.0.1:8222";
  conditions = ["[STATUS] == 200"];
  alerts = [{type = "ntfy";}];
};

and the Gatus aspect receives every entry from the machine as an argument:

den.aspects.gatus.nixos = {gatus-endpoint, ...}: {
  services.gatus.settings.endpoints = gatus-endpoint;
};

The firewall works the same way. My WireGuard aspect adds firewall-port.udp = [5553];, and the server opens all the ports its aspects asked for:

allowedUDPPorts = lib.concatMap (p: p.udp or []) firewall-port;

So my dashboard, my monitoring and my open ports always match what is actually installed. When I remove a service from the list, its tile, its check and its port go away with it.

Between machines

With den's policies, this also works across machines. Each machine declares its own WireGuard peer in its own file:

den.aspects.gila.wireguard-peer = {
  publicKey = "…";
  allowedIPs = ["192.168.100.4/32"];
};

and the WireGuard server collects the peers of all my machines:

den.policies.fleet-wireguard-peers = _: [
  (den.lib.policy.pipe.from "wireguard-peer" [
    (den.lib.policy.pipe.collect ({host, ...}: host != null))
  ])
];

To add a new machine to the VPN, I declare its key in its own config, and I don't need to edit the server's list of peers.

Impermanence

As I said in the last post, my laptop erases its root filesystem on every boot, so every folder that needs to be kept has to be declared. With den, each aspect declares its own folders. For Firefox:

den.aspects.firefox.includes = [
  (den._.persist {home.directories = [".mozilla"];})
];

The impermanence aspect then collects everything and passes it to the impermanence module. If I remove Firefox, .mozilla isn't kept anymore.

NixOS and Home Manager together

In a plain NixOS config, system settings and Home Manager settings live in two separate module systems. If one feature needs both, you write two modules and import them in two different places: one in the machine's config, the other in home-manager.users.<name>.

The dendritic pattern on its own already lets you put both in the same file, as flake.modules.nixos.foo and flake.modules.homeManager.foo, but you still have to import each one in the right place yourself.

With den, an aspect can have a nixos part and a homeManager part, and including the aspect once is enough: den applies the NixOS part to the machine and the Home Manager part to its users. My impermanence aspect does both:

den.aspects.impermanence = {
  nixos = {persist, lib, ...}: {
    environment.persistence."/persist".directories =
      lib.concatMap (p: p.nixos.directories or []) persist;
  };

  homeManager = {persist, lib, ...}: {
    home.persistence."/persist".directories =
      lib.concatMap (p: p.home.directories or []) persist;
  };
};

Machines and users

den makes a difference between a machine, a user, and a user on a specific machine. On my laptop, the desktop is configured for my user on that machine, under _.antoine:

den.aspects.balrog._.antoine.includes = [
  den.aspects.niri
  den.aspects.dms
  den.aspects.firefox
  den.aspects.theme
];

An aspect can also ask which user it's being applied to. My Git config takes my name and email from my user declaration instead of writing them again:

den.aspects.git = {user, ...}: {
  homeManager.programs.git.settings.user = {
    name = user.userName;
    email = user.email;
  };
};

Flake inputs

The last tool I use is flake-file. Instead of writing all the inputs in flake.nix, each module declares the inputs it needs, and flake.nix is generated with nix run .#write-flake. For example, my impermanence aspect starts with:

flake-file.inputs.impermanence.url = "github:nix-community/impermanence";

If I delete the aspect, the input goes away too.

The downsides

There's more to learn than with a classic config: aspects, batteries, quirks and policies come on top of the NixOS module system, and when something goes wrong the errors can be hard to follow.

den also looks at the names of a function's arguments (host, user…) to decide where to apply it. So replacing {host, ...} with _ changes what the code does, even though linters like deadnix suggest doing exactly that when the argument isn't used.

Finally, den is still young and changes quite a lot.

In summary

For a single machine, a normal config is probably enough. But with a server running many services and several machines that share things, den makes it much easier to add or remove something without forgetting a piece somewhere. If you want to see a complete example, the author of den shares his own config, vix.

Thanks for reading!

Why NixOS stopped my distro hopping

2026-10-30T00:00:00Z

I've been using NixOS for a while now, on my laptop and on the servers I self-host my stuff on. This post explains how I use it and why I think it's the best setup I've had so far.

Before NixOS I used Arch. I liked it, but I got tired of my system slowly drifting: packages I'd installed once and forgotten, config files I'd edited by hand, leftovers from things I'd tried. After a while it was full of garbage and I couldn't tell anymore what I had changed. With NixOS that doesn't happen, so I haven't had a reason to switch since.

My setup

I have three machines:

balrog, my laptop, running Niri with DankMaterialShell.
cyboogie, a server that hosts most of what I use day to day: photos with Immich, passwords with Vaultwarden, mail, music, documents with Paperless, my own Git forge, and a lot more. Around fifty services in total.
gila, a small VPS that monitors cyboogie and sends me a notification when something is down.

All three are configured from the same Git repository.

Configuring everything in one place

On most distros you install the system, then install packages and edit config files as you go. After a few years you end up with a machine where nobody really knows what was changed and why.

On NixOS you don't do that. The whole system is described in Nix files, and you apply them with nixos-rebuild switch. If I want Vaultwarden on my server, I add this to the config:

services.vaultwarden = {
  enable = true;
  config.ROCKET_PORT = 8222;
};

and rebuild. If I remove it, it's gone from the system on the next rebuild. Nothing is left behind.

Since the config is in Git, I also get the history of every change, and I can look up how anything is configured with a simple search in the repo, instead of looking around in /etc.

Rolling back

Each rebuild creates a new "generation", and the previous ones are kept. If an update breaks something, I can choose an older generation in the boot menu, or run nixos-rebuild switch --rollback, and I'm back to a working system.

Deploying from my laptop

I don't need to log into the servers to update them. Since all the configs are in the same repo, I can build any machine's system from my laptop and send it over SSH:

nixos-rebuild switch --flake .#gila --target-host gila --sudo

This is great for gila. It's a small VPS that would take ages to compile anything, so my laptop does the building and gila just receives the result and switches to it.

Erasing the system on every boot

Because the system is rebuilt from the config anyway, you can go one step further. On my laptop, / and /home are reset to an empty state every time it boots. Only the folders I list in my config are kept, using the impermanence module:

home.directories = [
  "Documents"
  "Downloads"
  ".ssh"
  ".local/share/fish"
];

I like this a lot. Programs can't leave files around my home folder forever, and the list of persisted folders is also the list of what I need to back up.

Running a server with fifty services

This is where NixOS helps me the most. Maintaining that many services alone would be a lot of work, but most of it is automated now:

Every input of my config is pinned in flake.lock, and every container image is pinned to a specific version and digest, so nothing changes unless I update it.
Every week, a job on my Forgejo instance updates flake.lock and opens a pull request. Renovate does the same for container images, and merges minor updates automatically.
On every pull request, CI builds the configuration of all three machines. If an update breaks something, I see it there before it reaches the server.
The builds go into my own binary cache, served by Harmonia, so my laptop downloads what CI already built instead of compiling it again.

Secrets

Passwords and API keys are in the same repository, encrypted with sops-nix. Each machine decrypts them with its own SSH host key, and only gets the secrets its config uses. When I set up a machine, I don't have to copy secret files around by hand.

The downsides

NixOS isn't easy to learn. You need to learn the Nix language, which is unusual, and the documentation is spread between the manual, the wiki, forum posts and other people's configs. Error messages can be hard to read.

Software that comes as a prebuilt binary can also be a problem, because it expects libraries in places that don't exist on NixOS. I use nix-ld on my laptop for that, and it works most of the time.

In summary

For me it's been worth it. I can rebuild any of my machines from scratch, undo a bad change, and always know what's running where. If you're curious, reading other people's configs is a good way to start. There are a lot of them on GitHub.

In the next post I'll explain how I organise my config with den, which made a big difference once the server got bigger.

Thanks for reading!