The Tool and the Language

Let’s bootstrap ourselves with some circular facts.

Nix is a tool for building (or “packaging”) software components using instructions expressed in the Nix language. The Nix language is even able to package the Nix tool (which is mostly written in C++), thus closing the epistemological loop.

The language features first-class treatment of filesystem paths and URLs (to source code and tarballs, for example). Nix expressions are evaluated in a hermetic environment with no path variables and no files. All outside references get copied into content-addressed folders in the store, and marked as build-time dependencies in any derivation that gets defined. Retained runtime dependencies are calculated by scanning the actual binary for store paths.

The Build

The component is the result of realizing the derivation. That means grabbing all the store path contents and combining them in the prescribed way. Imagine you have 3 components that are build-time dependencies:

1. A compiler
2. Source code
3. A bash script that uses the compiler to build the source

The derivation describes where to find these, and the (obvious) way that they fit together. The result is content-addressed with a hash based on all its dependencies, and placed in the store.

nixpkgs

It turns out this scheme is highly flexible and repeatable. nixpkgs is a repo full of Nix expressions for over 120,000 packages. You can pull any one of them into an ephemeral shell to try it out, or install it system-wide if you’re using:

NixOS

Finally, notice that “software components” could have a very broad definition. So broad, in fact, to include an entire OS with all of the installed programs and services. That’s what NixOS is: A Linux distro defined entirely in Nix and built around the /nix/store path model instead of the more usual FHS. I’ve written a bit about how the Nix module system helps encapsulate complex system recipes into simple one-liners.

All my homies use NixOS. To paraphrase from NixOS is the endgame of distrohopping :

No more configuration drift - solved ✅

“Works on my machine!” - solved ✅

Dependency Hell - solved ✅

Virtual and development environments - solved ✅

package management - solved ✅

Ready to go deeper?

To get started I highly recommend working through the tutorials at nix.dev!

• social problems caused by scaling organizations to thousands of engineers
• existing complexity
• laziness or desire to throw money at a problem rather than solve it

While they do solve real technical problems, I’ll argue here that there’s superior tooling for most use cases outside of big tech and legacy systems.

Containerize or Modularize?

We need deployment consistency and environment isolation, and containers solve those!

The 2016 essay Docker Considered Harmful explains how Linux primitives solve the same problems in a more robust way. One valid criticism of this is that Docker can get a junior developer productive more quickly without needing to learn about arcane system settings.

Fine, so we need an abstraction to work with.

Does the abstraction need to expose us to a bloated ecosystem prone to drift? What if it could evaluate to the precise, minimal, and correct system without introducing overhead? What if it’s a better Docker image builder than Docker’s image builder?

Enter Nix with its module system. Nix approaches the “dependency hell” problem from first principles. It requires a radically different mental model, which is itself a social organization problem. This model, by the way, is laid out best in Eelco Dolstra’s 2006 PHD Thesis (PDF).

When you think about

• polyglot system with multiple language ecosystems working together
• co-existing packages with conflicting dependencies (i.e dfferent versions of python)

do you get a headache thinking about all the setup? Well then you should probably swallow some Nix pills. No other tool can encapsulate cross-ecosystem practices and Linux expertise so cleanly. A simple configuration change like

services.postgres.enable = true;

is the tip of a carefully crafted reproducible iceberg. This line of code hides a host of system-level changes including

• User and groups setup with correct isolation and permissions
• Directory structure with ownership and permissions
• Initialization, default template databases
• SystemD service with correct dependencies, start order, lifecycle and recovery and much more!

It’s a massive setup process that would normally be done manually, maybe captured in brittle shell scripts, or containerized. But here it’s a one-liner, and it’s exposed for use as a declarative model that allows completely deterministic and atomic system upgrades!

So while containers provide language-agnostic deployment, Nix achieves the same universality at the package level while maintaining better reproducibility and lower overhead. You can even spit out a Docker image as an afterthought if that’s what you really need.

Cluster or Cluster*@!#?

We need service discovery, load balancing, and observability! Kubernetes provides these with a vast ecosystem of battle-tested tools, and its nice declarative operator pattern for nearly every infrastructure need.

The infrastructure problem is solved by creating different problems: cognitive overhead, ecosystem lock-in, long development cycles, and significant cost markup. There are compelling reasons to look for a better alternative.

Well, the largest package repo in the world (Nixpkgs) has nice modules defined for over 20,000 world-class open-source tools. With a 3-line change to your system configuration, you’re now building a robust set of tools:

services = {
  nginx.enable = true;      #Load balancing
  consul.enable = true;     #Service discovery
  prometheus.enable = true; #Observability
  #You'll want to configure these, of course.

But that’s not it. The Nix flake output schema specifies nixosConfigurations as a key. Note the plural. So you might do something like:

nixosConfigurations = {
  web = mkNode "web" {
    services.nginx.enable = true;
    services.nginx.virtualHosts."web" = {
      locations."/api/" = {
      proxyPass = "http://${cluster.db.ip}:5000/";
    };
    app.db_address = cluster.db.ip
  };

  db = mkNode "db" {
    services.postgresql.enable = true;
    services.postgresql.enableTCPIP = true;
    services.postgresql.authentication = ''
      host all all ${cluster.web.ip}/32 trust
      '';
    api.enable = true
  };
};

where the 2 nodes configurations make them aware of each other.

The same flake can even include

• integration tests using the insanely powerful integration test driver
• deployment metadata with deploy-rs to deploy the whole cluster with 1 command

So the question then becomes, do you have a nest of messy legacy code and need to throw money at scaling it up? Or do you have the luxury of using the tools directly and scaling piecewise as needs arise?

Summary

It’s never going to be easy to retrofit legacy enterprise systems. But for designing new systems, the NixOS advantage is massive. Your entire system configuration, from kernel to application dependencies to infrastructure services, is a single, reproducible, version-controlled artifact. It allows for

• One deployment mechanism
• Deterministic deployments
• Exact parity between development and production

and most importantly, a level of autonomy and sovereignty that you yield when your system is built on unstable abstractions.

1. SSH in and edit the configuration files (or copy them over) and then run nixos-rebuild switch which triggers the node to pull and build all the necessary items.

2. Check and build the configuration locally, and copy the entire closure across.

At a glance there might not be an advantage to one or the other. But consider if you’re deploying custom content that isn’t part of nixOS builtin configuration. To use method (1) you would need to clone all your repos on the server to be able to rebuild. Then every update requires you to ssh in and pull.

That’s why (2) is the much better option. We will use deploy-rs to implement it on DigitalOcean.

1) Enable flakes on the server

If you followed the previous instructions you’ve got a local folder full of configuration pulled from your node. Go ahead and turn that into a git repo before getting too far into this.

Adjust your configuration.nix

{ pkgs, ... }: {
  imports = [
    ./hardware-configuration.nix
    ./networking.nix
  ];

  environment.systemPackages = with pkgs; [ vim ];

  boot.tmp.cleanOnBoot = true;
  zramSwap.enable = true;
  networking.hostName = "your-hostname";
  networking.domain = "";
  services.openssh.enable = true;
  users.users.root.openssh.authorizedKeys.keys = [''your key here'' ];
  system.stateVersion = "25.05";

  nix.settings.experimental-features = [ "nix-command" "flakes" ];
}

The main changes are to add the content of host.nix (personal preference but you can go ahead and delete that), and enable the flakes feature. Push the whole configuration folder back up and do a rebuild:

rsync -av --delete --exclude='.git' ./ [node-name]:/etc/nixos/
ssh [node-name] "sudo nixos-rebuild switch --flake /etc/nixos#default"

2) Wrap the original configuration in a flake

Now, working locally again, create a new flake.nix:

{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
    deploy-rs = {
      url = "github:serokell/deploy-rs";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, deploy-rs }: let
    system = "x86_64-linux";
  in {
    nixosConfigurations.default = nixpkgs.lib.nixosSystem {
      inherit system;
      modules = [
        ./configuration.nix
      ];
    };

    deploy.nodes.default = {
      hostname = "[node-name]";
      profiles.system = {
        sshUser = "root";
        path = deploy-rs.lib.${system}.activate.nixos self.nixosConfigurations.default;
        user = "root";
      };
    };
    checks = builtins.mapAttrs (system: deployLib: deployLib.deployChecks self.deploy) deploy-rs.lib;
  };
}

This flake:

1. wraps the original system, importing it to nixosConfigurations.default.
2. describes the deployment target in deploy.nodes.default.

3) Deploy it

You can run deploy-rs straight from github:

nix run github:serokell/deploy-rs .#default

or hit a nix profile install github:serokell/deploy-rs so that you can just use the deploy command.

This should succeed and leave your server right where you started (since the actual configuration is unchanged), but now you have a nice flake to work with locally.

1) Set up a new droplet

• Choose Ubuntu 22.04
• Add SSH keys for something you have a local IdentityFile for.
• Under “Advanced Options” -> “Add initialization scripts” paste

#cloud-config
write_files:
- path: /etc/nixos/host.nix
  permissions: '0644'
  content: |
    {pkgs, ...}:
    {
      environment.systemPackages = with pkgs; [ vim ];
    }
runcmd:
  - curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIXOS_IMPORT=./host.nix NIX_CHANNEL=nixos-25.05 bash 2>&1 | tee /tmp/infect.log

2) SSH in and copy config down

Add the node’s SSH config to ~/.ssh/config

Host [node-name]
        HostName [IP-address]
        User root
        IdentityFile ~/.ssh/[identity]

Now you should be able to ssh [node-name] and cat /etc/nixos/configuration.nix to see your new system.

Start a new directory for containing the node’s configuration locally. Maybe call it [node-name]-deployment.

On the server, run scp [node-name]:/etc/nixos/* ..

Now you’ve got the remote configuration in hand. If you wanted to alter the node, the naive way to do it is edit the configuration, push it back over, and run sudo nixos-rebuild switch. But there’s a better way to approach this that involves building the system locally. We’ll continue in setting up deploy-rs.