I’ve recently purchased a Hetzner EX44 dedicated server, and despite a good number of blog or wiki articles about how to deploy NixOS on baremetal at Hetzner, I did not find one that worked out of the box for this specific model. So here is a quick recap of how I’ve managed to configure the server.

Pre-deployment Planning

Before thinking of deploying NixOS, the first step is to understand what network and disk configuration will work for your server.

Networking Configuration

Hetzner requires configuring static IP addresses, and its Robot dashboard provides everything that’s needed to do that.

IPv4 Configuration

• IP: the server IP address
• Gateway: the gateway address
• Mask: the server subnet mask
• Prefix: compute this from the subnet mask, ex: 255.255.255.224 -> /27

IPv6 Configuration

• IP: the server IPv6 address
• Gateway: the IPv6 gateway address
• Prefix: usually /64

DNS

Do not forget to add DNS servers to the network config, this is quite useful if you need to debug the installation using the virtual KVM.

Firewall

It is good practice to configure the firewall to allow only the necessary ports. This is pretty standard but there is one gotcha: you will need to allow incoming ACK TCP packets so that your server can establish outside TCP connections.

Disk Setup

The bootloader setup that is supported on Hetzner servers is documented at Hetzner EFI System Partition. Basically, this boils down to creating an ESP partition that is at least 200MB large.

Installing NixOS with nixos-anywhere

In the past, I’ve personally installed NixOS on various computers using a multitude of methods. The last time I set up a dedicated server with NixOS was manually using kexec to boot a basic NixOS image and install NixOS from there.

With this new server, I’ve searched for new methods and found that nixos-anywhere was the one I liked the most. First, it was easily reproducible; second, it integrates with disko, which handles disk partitioning; third, it actually works.

Here’s a sample configuration I used with nixos-anywhere:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nixos-anywhere = {
      url = "github:nix-community/nixos-anywhere";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    disko = {
      url = "github:nix-community/disko";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, nixos-anywhere, disko, ... }: {
    nixosConfigurations.ex44 = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        disko.nixosModules.disko
        ./disk-config.nix
        ./network-config.nix
      ];
    };
  };
}

For disk configuration, I created a simple disk-config.nix file setting up a raid1 partition for /boot and creating a mirror zfs pool for the rest of the disk:

# disk-config.nix
{ ... }:
let
  mirrorBoot = idx: {
    type = "disk";
    device = "/dev/nvme${idx}n1";
    content = {
      type = "gpt";
      partitions = {
        ESP = {
          size = "1G";
          type = "EF00";
          content = {
            type = "mdraid";
            name = "boot";
          };
        };
        zfs = {
          size = "100%";
          content = {
            type = "zfs";
            pool = "zroot";
          };
        };
      };
    };
  };
in {
  disko.devices = {
    disk = {
      nvme0n1 = mirrorBoot "0";
      nvme1n1 = mirrorBoot "1";
    };

    mdadm = {
      boot = {
        type = "mdadm";
        level = 1;
        metadata = "1.0";
        content = {
          type = "filesystem";
          format = "vfat";
          mountpoint = "/boot";
          mountOptions = [ "umask=0077" ];
        };
      };
    };

    zpool = {
      zroot = {
        type = "zpool";
        mode = "mirror";
        rootFsOptions = {
          compression = "lz4";
          acltype = "posixacl";
          xattr = "sa";
          "com.sun:auto-snapshot" = "true";
          mountpoint = "none";
        };
        datasets = {
          "root" = {
            type = "zfs_fs";
            options = { mountpoint = "none"; };
          };
          "root/nixos" = {
            type = "zfs_fs";
            options.mountpoint = "/";
            mountpoint = "/";
          };
          "root/home" = {
            type = "zfs_fs";
            options.mountpoint = "/home";
            mountpoint = "/home";
          };
          "root/tmp" = {
            type = "zfs_fs";
            mountpoint = "/tmp";
            options = {
              mountpoint = "/tmp";
              sync = "disabled";
            };
          };
        };
      };
    };
  };
}

The network configuration is also fairly straightforward:

# network-config.nix
{ ... }: {
  networking = {
    hostId = "a 32bit host id for zfs";

    hostName = "ex44";
    useDHCP = false;

    # Disable predictable interface names because the server only has one network card and, ironically, it makes the configuration a bit more predictable.
    usePredictableInterfaceNames = false;

    interfaces."eth0" = {
      ipv4.addresses = [{
        address = "your.server.ip";
        prefixLength = 27; # computed from the mask
      }];
      ipv6.addresses = [{
        address = "your:server:ipv6::address";
        prefixLength = 64;
      }];
    };
    defaultGateway = "your.gateway.ip";
  };
}

To deploy using nixos-anywhere from the rescue system, I simply ran:

nix run github:nix-community/nixos-anywhere -- --flake .#ex44 --target-host root@your.server.ip --generate-hardware-config nixos-generate-config hardware-configuration.nix --disko-mode disko

In the end, following the nixos-anywhere quickstart tutorial with a configuration that matches the requirements we gathered earlier worked perfectly.

Post-Installation Management

Once the server is up and running with NixOS, you can fall back to your preferred way of deploying it. As for myself, I use comin which allows me to have a GitOps workflow for managing my servers. In a later article, I’ll explain how to automatically upgrade the flake inputs and also have a nice workflow to show the derivation diffs on PRs to the flake repository.

If you run into issues with your deployment, the Hetzner KVM console can be a lifesaver - it gives you direct console access even when networking isn’t working yet.

Acknowledgments

I’ve mentioned reading a few articles on deploying Nixos to Hetzner servers and I’d like to list them here because they were super useful to me:

• NixOS on Hetzner Dedicated via mhu.dev.
• Install NixOS on Hetzner Online.
• Eve disko configuration via Mic92 dotfiles.
• nixos-anywhere.

His thoughts on building reliable software carry significant implications for both developers and stakeholders alike:

It is much easier to add features to reliable software, than it is to add reliability to featureful software.

This quote illustrates a common misconception in software development cycles. Many organizations misinterpret the principle of shipping early, viewing it as permission to rush out buggy features quickly. However, the value lies in delivering small, reliable components first, then iteratively building upon that stable foundation. This approach gives us practical insight into our design decisions and their real-world effectiveness. Another important but frequently neglected aspect kqr highlights is the importance of establishing clear boundaries and limits in our systems.

I’ve learned through experience that seemingly functional code often breaks down precisely because it lacks defined constraints, eventually depleting critical resources. When these issues emerge, implementing fixes becomes increasingly difficult and expensive. That’s why designing a system, should includes deliberate consideration of it’s intended capacity, imposing appropriate limitations rather than allowing unchecked growth.

The article also explores other significant aspects of reliable software design, such as the importance of testing, simplicity, and working with existing solutions. A thoroughly enjoyable and insightful read!

There was just one problem: it’s not available on NixOS which my home computer is running on. I decided to package it myself.

Fortunately, the packaging process turned out to be relatively straightforward, though with a few interesting challenges. Since claude-code isn’t open-source, we need to work with the npm-hosted version.

I’m documenting my packaging approach below to help fellow NixOS users who want to use this tool.

{ lib, buildNpmPackage, fetchurl, nodejs, makeWrapper, writeShellScriptBin }:

let
  # Main package
  claudeCode = buildNpmPackage rec {
    pname = "claude-code";
    version = "0.2.29";

    src = fetchurl {
      url = "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-${version}.tgz";
      hash = "sha256-1iKDtTE+cHXMW/3zxfsNFjMGMxJlIBzGEXWtTfQfSMM=";
    };

    npmDepsHash = "sha256-fuJE/YTd9apAd1cooxgHQwPda5js44EmSfjuRVPbKdM=";

    inherit nodejs;

    makeCacheWritable = true;

    postPatch = ''
      if [ -f "${./claude-code/package-lock.json}" ]; then
        echo "Using vendored package-lock.json"
        cp "${./claude-code/package-lock.json}" ./package-lock.json
      else
        echo "No vendored package-lock.json found, creating a minimal one"
        exit 1
      fi
    '';

    dontNpmBuild = true;
    dontNpmInstall = true;

    nativeBuildInputs = [ makeWrapper ];

    # Create a custom installation phase to handle the package organization
    installPhase = ''
      # Create a directory for the lib files
      mkdir -p $out/lib/node_modules/@anthropic-ai/claude-code

      # Copy all package files to the lib directory
      cp -a . $out/lib/node_modules/@anthropic-ai/claude-code/

      # Create bin directory
      mkdir -p $out/bin

      # Create a wrapper script that points to the actual CLI script
      makeWrapper ${nodejs}/bin/node $out/bin/claude-code \
        --add-flags "$out/lib/node_modules/@anthropic-ai/claude-code/cli.mjs"
    '';

    meta = with lib; {
      description = "Claude Code CLI tool";
      homepage = "https://www.anthropic.com/claude-code";
      mainProgram = "claude-code";
    };
  };

  # Helper script to update the package-lock.json file
  #
  # Build with `nix build .#claude-code.updateScript`
  updateScript = writeShellScriptBin "update-claude-code-lock" ''
    #!/usr/bin/env bash
    set -e

    if [ $# -ne 1 ]; then
      echo "Usage: update-claude-code-lock <version>"
      echo "Example: update-claude-code-lock 0.2.29"
      exit 1
    fi

    VERSION="$1"
    TEMP_DIR=$(mktemp -d)
    LOCK_DIR="$PWD/packages/claude-code"

    echo "Creating $LOCK_DIR if it doesn't exist..."
    mkdir -p "$LOCK_DIR"

    echo "Downloading claude-code version $VERSION..."
    curl -L "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-$VERSION.tgz" -o "$TEMP_DIR/claude-code.tgz"

    echo "Extracting tarball..."
    mkdir -p "$TEMP_DIR/extract"
    tar -xzf "$TEMP_DIR/claude-code.tgz" -C "$TEMP_DIR/extract"

    echo "Generating package-lock.json..."
    cd "$TEMP_DIR/extract/package"
    ${nodejs}/bin/npm install --package-lock-only --ignore-scripts

    echo "Copying package-lock.json to $LOCK_DIR..."
    cp package-lock.json "$LOCK_DIR/"

    echo "Cleaning up..."
    rm -rf "$TEMP_DIR"

    echo "Done. Package lock file updated at $LOCK_DIR/package-lock.json"
    echo "You may need to update the npmDepsHash in your claude-code.nix file."
    echo "Use: prefetch-npm-deps $LOCK_DIR/package-lock.json"
  '';
in
  # Return both the package and the update script
  claudeCode // {
    updateScript = updateScript;
    passthru = (claudeCode.passthru or {}) // {
      inherit updateScript;
    };
  }

Here are the few highlights about the packaging process:

1. The package needs to be sourced directly from the npm registry:

        src = fetchurl {
            url = "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-${version}.tgz";
            hash = "sha256-1iKDtTE+cHXMW/3zxfsNFjMGMxJlIBzGEXWtTfQfSMM=";
        };
   

2. We vendor the package-json.lock file because the source does not include it.

        postPatch = ''
        if [ -f "${./claude-code/package-lock.json}" ]; then
            echo "Using vendored package-lock.json"
            cp "${./claude-code/package-lock.json}" ./package-lock.json
        else
            echo "No vendored package-lock.json found, creating a minimal one"
            exit 1
        fi
        '';
   

3. To make future updates easier, I’ve included a helper script that automatically generates the package-lock.json file from the npm registry:

    # Helper script to update the package-lock.json file
    #
    # Build with `nix build .#claude-code.updateScript`
    updateScript = writeShellScriptBin "update-claude-code-lock" ''
    #!/usr/bin/env bash
    set -e
   
    if [ $# -ne 1 ]; then
        echo "Usage: update-claude-code-lock <version>"
        echo "Example: update-claude-code-lock 0.2.29"
        exit 1
    fi
   
    VERSION="$1"
    TEMP_DIR=$(mktemp -d)
    LOCK_DIR="$PWD/packages/claude-code"
   
    echo "Creating $LOCK_DIR if it doesn't exist..."
    mkdir -p "$LOCK_DIR"
   
    echo "Downloading claude-code version $VERSION..."
    curl -L "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-$VERSION.tgz" -o "$TEMP_DIR/claude-code.tgz"
   
    echo "Extracting tarball..."
    mkdir -p "$TEMP_DIR/extract"
    tar -xzf "$TEMP_DIR/claude-code.tgz" -C "$TEMP_DIR/extract"
   
    echo "Generating package-lock.json..."
    cd "$TEMP_DIR/extract/package"
    ${nodejs}/bin/npm install --package-lock-only --ignore-scripts
   
    echo "Copying package-lock.json to $LOCK_DIR..."
    cp package-lock.json "$LOCK_DIR/"
   
    echo "Cleaning up..."
    rm -rf "$TEMP_DIR"
   
    echo "Done. Package lock file updated at $LOCK_DIR/package-lock.json"
    echo "You may need to update the npmDepsHash in your claude-code.nix file."
    echo "Use: prefetch-npm-deps $LOCK_DIR/package-lock.json"
    '';
   

4. The standard npm install phase doesn’t work for this package, so we implement a custom approach:

        dontNpmBuild = true;
        dontNpmInstall = true;
   
        nativeBuildInputs = [ makeWrapper ];
   
        # Create a custom installation phase to handle the package organization
        installPhase = ''
            # Create a directory for the lib files
            mkdir -p $out/lib/node_modules/@anthropic-ai/claude-code
   
            # Copy all package files to the lib directory
            cp -a . $out/lib/node_modules/@anthropic-ai/claude-code/
   
            # Create bin directory
            mkdir -p $out/bin
   
            # Create a wrapper script that points to the actual CLI script
            makeWrapper ${nodejs}/bin/node $out/bin/claude-code \
                --add-flags "$out/lib/node_modules/@anthropic-ai/claude-code/cli.mjs"
        '';
   

This wrapper script approach keeps the binary directory clean while ensuring the CLI has access to all its required dependencies.

EDIT(2025-03-03): phanirithvij rightfully pointed out that the package has been merged to nixos-unstable: claude-code: init at 0.2.9 by malob

When dealing with Rails upgrades, or with generator *:install commands, I often find that figuring out the diffs and what needs to get updated or removed is the least enjoyable part of the process.

I have yet to try this tool, but lately I’ve been thinking of a few ways to improve this process:

1. Make the diff easier to deal with by adding your own edits at the end of the generated files, unless changing a generated option value.
2. Move your own changes to dedicated files which, by limiting the changes to the generated files to a minimum, would make dealing with diffs easier.

Either way, I’ll try these approaches on our applications at work and hopefully make upgrading Rails an enjoyable experience.

While automated translation isn’t revolutionary on its own, Honyaku’s business impact is striking:

Created because it replaced a $34K/year SaaS contract and streamlined our deploy process.

This case perfectly illustrates the power of focused software development: building a targeted solution to a specific problem can drastically cut costs.

It’s fascinating how this practical approach often delivers better, more efficient results than using off-the-shelf, expensive services.

From my experience, this problem-first mindset typically leads to solutions that are both simpler and more economical.

N+1 queries often significantly impact application performance. Having reliable detection tools in our arsenal is essential for maintaining efficient database interactions.

I’ve recently dealt with removing N+1 queries on an application, leading to 2x latency improvements. That system also suffered from another kind of N+1 problem - it looked up a ton of cache keys in Redis, which I’ve changed to a single lookup, avoiding unnecessary roundtrips to the cache.