Luka builds things

My consultancy stack

2026-07-17T00:00:00.000Z

If you don't know yet, I've started my own IT consultancy! Yay!

The most interesting part, from a builder's perspective of course, was thinking about what new services I'll likely need to spin up in my homelab.

Let's take a look at a few areas we need to cover in our one-man-consultancy.

Tracking opportunities and getting clients

Before you start working for a client, you first have to find them and then negotiate with them and convince them you're the one to help solve their problem, whatever that might be. Since you're likely not talking with just one client, you'll want to track this process for each client separately. So what you'll need is a CRM system.

I've looked at a few and the one I've decided to self-host is EspoCRM.

You can self-host it on your own server for free, it integrates with your email and supports OIDC authentication!

I like its simplicity and ease of use.

One thing I dislike about it is that its built-in calendar and meeting tracking system does not expose or integrate with CalDAV natively. Which brings us to the next thing you'll need.

Calendar

You'll have lots and lots of meetings with clients. So having a calendar is essential.

I used to use NextCloud for that, but recently I switched over to Rustical, so this is now my calendar and contacts server.

I use Thunderbird for interacting with my calendar on my laptop and on the mobile I use Etar via DAVx5. All of this works great.

Bonus point, Rustical works great with OIDC.

Task management

Even before opening your consultancy you'll have a lot of tasks to do. For example, you'll need to actually register your consultancy, open a bank account, manage your insurance and so on. You'll want to track these things!

The winner in this category for me was Vikunja.

This one was easy to choose because it's a mature service and ticks all the boxes for me. The most important being OIDC authentication.

I like that it's not bloated and is very snappy.

So far, I have no complaints about this one.

Time tracking

Doing a project for a paying client means they would (generally) like to know where your time has gone, so you'll need to have a way of showing that to the client. Most of the projects are also paid by-the-hour, so knowing how many hours a project took is important.

For this Kimai was chosen.

It's a very mature project and it has been great so far. There are also a lot of community developed apps like kimai-clock (macOS menu bar app).

Feels polished and has many knobs you can turn to get it tuned just right.

One thing that almost turned me towards other solutions was a lack of OIDC login. Luckily for me it does support LDAP login, which is what my OIDC provider (Authelia) uses as the user store.

Invoicing

While Kimai can also do invoicing, this is something that I decided not to self-host, due to future regulatory requirements.

For this I'm using a local service Cebelca. It's used by a lot of Slovenian entrepreneurs and is a kind of go-to for invoicing.

It's free for up to 15 invoices per month and is just a joy to use.

I love its simple interface.

If I had to critique something, I'd point out that the invoice customization with a logo could be a bit better, since the size of the logo you upload (in pixels) is the size you'll see on the PDF.

Development environment

At first I thought I'll have to buy a beefy MacBook Pro for me to develop on, but since it's not cheap, and I already have a beefy server, I decided I'll just use the server for development and I bought a MacBook Air instead.

I have Incus running on the server (see Declarative Incus on NixOS with SSO), so my current workflow is that whenever I get a new client, I spin up a new VM just for that client and work on their projects in that VM exclusively.

So each morning I SSH into the VM of the client whose project I'll work on. Zellij (a terminal multiplexer) auto-attaches and I'm presented with the exact state that I left yesterday on. I usually run Emacs in one tab, then I have multiple other tabs open for running shell commands, following logs and driving Claude Code. All of this works just as it would on my laptop!

Even testing out web apps is not an issue. SSH supports port forwarding, so opening localhost:1234 is forwarded to the VM to the same (or a different) port, allowing inspection and quick iteration.

There are a few benefits to this VM development approach:

no cross contamination: git credentials, SSH keys, API keys; all of these are scoped per client, so I just can't accidentally commit with a wrong identity
persistent environment: you can update/restart your Mac without closing your editor or stopping a long running test or a compilation
declarative: each VM has its own NixOS configuration, with client-specific setup
not a macOS: macOS is great, but sometimes it just adds friction, e.g. ARM vs x86 docker containers
close to deployment environment: it's a Linux VM and you can make it as close as you want to the actual target deployment environment for the service

What about cons?

file access: if you want to send something to the client (e.g. a parsed CSV), you first have to rsync it to your laptop
you need the server: if your server isn't online, you can't work
no offline work: if you're not online, you can't work either
no clipboard: copying text is a bit more involved than it would be on your laptop

Try it out, it's been great for me so far.

Email and website

This is something that I already had before starting a consultancy and I think it's a must-have.

Running a website is simple, you can just chuck an HTML file and point Caddy to it.

As for emails, they are quite important, and I've read all sorts of horror stories about self-hosting this on residential ISPs that I'm letting Migadu take care of that one for me. I do use Thunderbird for this as well on my Mac and I bought Fairmail for my phone. Recommend both!

Conclusion

Running a consultancy is not easy, but having great open-source projects that you can rely on, makes it a bit easier.

Looking back at the list, it's apparent how much OIDC drove my choices.

If you're running your own consultancy on a different set of tools, I'd love to hear about it, feel free to email me.

Turn your server into a family game streaming hub

2025-11-04T00:00:00.000Z

If you've read my My hardware post, you've seen that I had a gaming PC at some point. I cannibalized its graphics card for my server to run speech-to-text models on it for my Home Assistant, which means no more gaming for me.

Or does it?

VM gaming

For a while, before I ran the STT model on it, I created a gaming VM, passed through the graphic card and gamed on it. It worked fine!

The server was under my desk, so I could just connect the output of the GPU to my screen, plug in (and pass through) my keyboard, mouse and headphones and off I went.

Still, not everything is great with VM gaming:

it's a hassle to turn on the VM, I had to SSH into the server to turn it on
GPU can only be used by the VM, you can't share it with other processes on the server
you have to be smart about disk space management, you either go with thinly provisioned storage (speed penalty), or possibly over-provision
you can't share a VM for gaming with multiple people practically

So while it worked ok for my use case, I yearned for more.

That's when I discovered container gaming.

Container gaming

While trying to set up headless LXC container with Incus (see my post about setting up Incus with SSO), I came across Games on Whales.

Their tagline is "Stream multiple virtual desktops and games running in Docker!", and that is exactly what it does.

On your server, you run their container called wolf which itself runs a Sunshine-like application. You then pair it with your Moonlight client running on your laptop or TV and once that is done, you can start up various applications or desktops.

They have a good default selection:

You can add your own applications/containers later if you wish, I have yet to do so.

Moonlight passes through your input devices (keyboard+mouse/gamepad) and streams back the application GUI.

Sunshine + Moonlight

If you haven't heard about either of them, they are desktop streaming protocols, not that different from VNC or RDP, but made for low-latency high-quality remote gaming or desktop streaming.

Sunshine is the 'server' part, or something that you install on the PC you want to stream from, while the Moonlight client is installed on your laptop or TV, where you want to stream to.

How it works under the hood

I won't go into too much detail, but the gist of it is that it relies heavily on containers.

So the 'main' container (wolf) acts as a Sunshine server, allowing Moonlight clients to pair with it. It's not a real Sunshine server though, it just talks the talk.

Currently you pair it by opening a URL wolf gives you in its container logs (something like https://your.host/pin/#123D3240715B5C74), which leads to an input form where you can input the PIN that was given to you by the Moonlight client.

Once paired, you can view the applications in Moonlight. When starting an application, wolf starts a container related to that application, mounts your data and your graphics card and starts the stream.

For example if you selected the Steam app, wolf will:

start SteamApp_1234567890 container, where the number is the internal ID of your user
create a folder 1234567890 (on your server) where it will store all your user app data
mount a sub-folder into the container, e.g. 1234567890/Steam will be mounted into the container at ~/
mount your graphics card so that it will be used by Steam to render games
set up audio (via I think another separate container?)
map through your input devices
probably more stuff that I'm not aware (yet)

The result is amazing. It works great, the latency is very low, I was getting 60 FPS of crisp images and the sound was of high quality.

To give you some concrete numbers:

On my laptop over 5GHz WiFi: steady 60 FPS, 6ms network latency, 4ms decoding latency
On my NVidia Shield TV over gigabit cable: 1920x1080 at steady 60 FPS, 1ms network latency, 1.5ms decoding latency

Not all is roses though.

Security Considerations

One critical caveat: For wolf to spawn new containers, you must give it access to the Docker/Podman socket.

This essentially gives wolf root-level control over your entire container infrastructure, meaning it can start, stop, and access any container on your system.

How significant this risk is depends on your setup. I run 95% of my services on bare metal, so not in containers, and the other 5% are stateless services (Gotenberg and Apache Tika) and TubeSync. So nothing really private.

You have been warned!

Setting it all up

For this part I'm just going to share my NixOS module as it is. It contains some of my specifics, but you'll get the gist of it and you'll be able pick and choose the parts that are of interest for you.

I followed the "Nvidia (Manual)" method from their guide since I have an NVidia GeForce 1070 GPU.

Here is the module:

{
  config,
  lib,
  pkgs,
  ...
}:
with lib;

let
  # This config itself
  cfg = config.my.services.wolf;
  # Name the container
  containerName = "wolf";
  # A reference of ports that are use by wolf
  ports = {
    https = 47984;
    http = 47989;
    control = 47999;
    rtsp = 48010;
    video = 48100;
    audio = 48200;
  };
  # A shortcut
  backend = config.virtualisation.oci-containers.backend;
  # Name typo-less reference
  nvidiaVolumeName = "nvidia-driver-vol";
in
{
  options.my.services.wolf = with lib.types; {
    enable = mkEnableOption "wolf";

    # Where we'll persist our user data and config
    dataDir = mkOption {
      type = path;
      default = "/var/my/wolf";
    };

    # On which address to listen on
    httpAddress = mkOption {
      type = str;
      default = "127.0.0.1";
    };
    
    httpPort = mkOption {
      type = int;
      default = ports.http;
    };

    # On which domain it will be accessible
    domain = mkOption {
      type = str;
      default = "wolf.${my.domain}"; # Resolves to something like `wolf.example.com`
    };
  };

  config = mkIf cfg.enable {
    # Enable NVIDIA Container Toolkit if GPU support is requested
    hardware.nvidia-container-toolkit.enable = true;

    # Needed to get working virtual input devices
    boot.kernelModules = [
      "uinput"
    ];

    # The `virtualisation.oci-containers.containers."${containerName}" ` option below creates this systemd service
    # We add a preStart script to it, to setup nvidia volume and do some cleanup
    systemd.services."${backend}-${containerName}" = {
      preStart = ''
        # Setup the nvidia volume
        ${pkgs.curl}/bin/curl https://raw.githubusercontent.com/games-on-whales/gow/master/images/nvidia-driver/Dockerfile | ${backend} build -t gow/nvidia-driver:latest -f - --build-arg NV_VERSION=$(cat /sys/module/nvidia/version) .
        ${backend} create --rm --mount source=${nvidiaVolumeName},destination=/usr/nvidia gow/nvidia-driver:latest sh

        # Stop/remove games-on-whales containers if they are running
        ids=$(${backend} ps --all --format ' ' | grep 'games-on-whales' | ${pkgs.busybox}/bin/awk '{print $1}')
        if [ -n "$ids" ]; then
          ${backend} stop $ids || true
          ${backend} rm $ids || true
        fi
      '';
    };

    # Define the main `wolf` container
    virtualisation.oci-containers.containers."${containerName}" = {
      autoStart = true;
      image = "ghcr.io/games-on-whales/wolf:stable";
      volumes = [
        "${cfg.dataDir}:/etc/wolf:rw"
        "/run/${backend}/${backend}.sock:/var/run/docker.sock:rw"
        "/dev/:/dev/:rw"
        "/run/udev:/run/udev:rw"
        "${nvidiaVolumeName}:/usr/nvidia:rw"
      ];
      devices = [
        "/dev/dri"
        "/dev/uinput"
        "/dev/uhid"
        "/dev/nvidia-uvm"
        "/dev/nvidia-uvm-tools"
        "/dev/nvidia-caps/nvidia-cap1"
        "/dev/nvidia-caps/nvidia-cap2"
        "/dev/nvidiactl"
        "/dev/nvidia0"
        "/dev/nvidia-modeset"
      ];
      ports = [
        "${toString ports.https}:47984/tcp"
        "${toString cfg.httpPort}:47989/tcp"
        "${toString ports.control}:47999/udp"
        "${toString ports.rtsp}:48010/tcp"
        "${toString ports.video}:48100/udp"
        "${toString ports.audio}:48200/udp"
      ];
      extraOptions = [
        "--pull=newer"
        "--device-cgroup-rule"
        "c 13:* rmw"
      ];
      environment = {
        NVIDIA_DRIVER_VOLUME_NAME = nvidiaVolumeName;
      };
    };

    # Open up the ports on the VM
    networking.firewall = {
      allowedTCPPorts = [
        ports.https
        cfg.httpPort
        ports.rtsp
      ];
      allowedUDPPorts = [
        ports.control
        ports.video
        ports.audio
      ];
    };

    services.udev.extraRules = ''
      # Allows Wolf to acces /dev/uinput
      KERNEL=="uinput", SUBSYSTEM=="misc", MODE="0660", GROUP="input", OPTIONS+="static_node=uinput"

      # Allows Wolf to access /dev/uhid
      KERNEL=="uhid", TAG+="uaccess"

      # Move virtual keyboard and mouse into a different seat
      SUBSYSTEMS=="input", ATTRS{id/vendor}=="ab00", MODE="0660", GROUP="input", ENV{ID_SEAT}="seat9"

      # Joypads
      SUBSYSTEMS=="input", ATTRS{name}=="Wolf X-Box One (virtual) pad", MODE="0660", GROUP="input"
      SUBSYSTEMS=="input", ATTRS{name}=="Wolf PS5 (virtual) pad", MODE="0660", GROUP="input"
      SUBSYSTEMS=="input", ATTRS{name}=="Wolf gamepad (virtual) motion sensors", MODE="0660", GROUP="input"
      SUBSYSTEMS=="input", ATTRS{name}=="Wolf Nintendo (virtual) pad", MODE="0660", GROUP="input"
    '';

    systemd.tmpfiles.rules = [
      # Create he data dir if it does not exist
      "d ${cfg.dataDir} 750 root root"
      # create a small file that indicates to borgmatic that this folder should not be backed up
      "f ${cfg.dataDir}/${config.my.services.borgmatic.noBackupFilename} 755 root root"
    ];

    # I use ephemeral root partition, so we indicate that this data is to be persisted across reboots
    # This maps to some Impermanence option
    my.persisted.directories = [
      cfg.dataDir
    ];

    # Make the web part accessible
    my.services = {
      proxy.reverseProxies = [
        {
          from = cfg.domain;
          to = "${cfg.httpAddress}:${toString cfg.httpPort}";
        }
      ];
      # Only allow accessing this internally, from LAN
      authelia = {
        accessRules = [
          {
            domain = cfg.domain;
            whenInternal = true;
            policy = "two_factor";
          }
        ];
      };
    };
  };
}

I'm using the podman backend on my server, but it should work the same for docker. You can restart the container (and all of its associated containers) with systemctl restart podman-wolf (or systemctl restart docker-wolf if you're using the docker backend).

A few tips and tricks

Sharing user folders between multiple clients

wolf treats each paired client as a separate user by default, which means each client gets its own home folder in the containers. If you have multiple devices, it is possible to share the home folder by editing the config file by hand a bit.

Pair the second client to get the entries and then open up the config file at /var/my/wolf/cfg/config.toml. Find the [[paired_clients]] entries and make sure that both of your clients have the same app_state_folder ID by using the ID of your first client (that likely already has some data in that folder).

I restarted the service for good measure.

Mounting additional folders into the containers

If you have some ROMs (or other files) on your server, that you want to make available to your RetroArch container (and others), you can do that by creating a volume mapping.

Edit the /var/my/wolf/cfg/config.toml file. Find [[apps]] with the title of the application you want to add the mapping to (e.g. title = 'RetroArch') and edit mounts array to add your volume (it's in the [apps.runner] section).

Here is how I mounted my downloads folder from the server (/mnt/pool/download/) to the container at /download.

mounts = [ '/mnt/pool/download/:/download:rw' ]

Now I can easily download mods or other things on the server and have the downloads show up in the containers.

Don't forget to restart!

Conclusion

I've been using this setup for a few weeks now and have found it to be reliable and performant.

I'm using it on my laptop and on my NVidia Shield which is connected to the TV. I can pass through gamepads and keyboard/mouse.

For me, performance- and usability-wise it's on par with Parsec, which has been my go-to service for streaming in the past, but without any external services or accounts. It's all self-hosted.

Since I'm the only one in my household that games at this moment, I sadly can't comment on how well the multi-user aspect works. I'll let you know when my kids start gaming. Hopefully the GPU prices will have come down by then and we'll be able to pool our money and replace my aging GeForce 1070.

I hope this post has been valuable and let me know if you run into any issues (email is on my homepage)!

A kid-friendly DIY jukebox

2025-10-14T00:00:00.000Z

I grew up in the music CD era, which meant I could take a look at our family CD collection, pick what I wanted to listen to, pop it into a CD player and voila, music! The collection was not that big, it was music that my parents liked, but at least I had agency. I could listen to music without involving anyone else from a very young age.

Today, most kids aren't that lucky. All they can do is ask their parents to play something for them on their phone/TV. Or what is even worse, they have their own phone/tablet with YouTube. Additionally, they are tracked, have to be online and have to interact with screens.

The solution?

Build an offline screen-free jukebox together with your kids. It's fun, you'll learn something and the kids will love using it.

Who is this guide for

I think this DIY project is quite approachable, that said, what is easy for me might be hard for you and vice versa. Also, I have quite a few years of Linux experience, I've completed projects with Raspberry Pis before and I have soldered a few PCBs in my time. So I generally knew what I needed to do going in.

You will need to know how to:

find the IP of a machine on your network
SSH into that machine
run (copy/pasted) commands on that machine
do some light soldering

As always, if you need help with anything feel free to email me.

What kind of jukebox

A PhonieBox!

It's a free, open-source, DIY jukebox aimed at kids. Everything you need to build it can be found at their GitHub repository.

Basically you use a Raspberry Pi, attach a speaker and a card reader to it. Then you install PhonieBox software on it, copy over the music files and link them with RFID cards. The kids can then tap the cards to the card reader and music starts playing. Simple as that!

Let's build it.

What you'll need

Now I've had a few of these things lying at home already. I just had to buy the card reader, RFID cards and some jumper cables totaling 18,47€.

I've bought them from az-delivery.de:

a card reader
- to read the cards
- 6,49€
jumper cables
- to connect the reader to the Pi
- 6,99€
some RFID cards
- to associate them with songs/folders/playlists/actions
- 4,99€

What you probably already have:

Raspberry Pi 1
- the brains of the operation
- any Pi works, PhonieBox folks suggest either a 2 or a 3
an SD card (or MicroSD + SD Adapter)
- it's where we'll install the OS and put the files
An old JBL speaker box
- on mine, the battery is dead, but that is okay, since it will be powered by the Pi via MicroUSB
- has an AUX input
AUX-to-AUX cable
- to connect the Pi and the JBL
2 x USB-to-MicroUSB cable
- one for powering the Pi and another for powering the JBL
USB Power Adapter
- provides power to the Pi
a nice box for the whole thing
card sleeves and some paper for marking the cards

As for the tools:

a soldering iron
some tape
a marker pen

The hardware assembly

Solder the pin headers to the card reader and attach the jumper cables. Note the colors of the jumper cables, as we'll connect it to the Pi next.

It's a bit fiddly to connect the cables to the Pi. Here is how the end result looks like.

Note: If you have different version of the Pi, please adjust the jumper cables connections on the Pi side according to your pinout diagram.

That was the hard part.

Next, just connect the JBL speaker with AUX and USB cable to the Pi, to get sound and power.

Here is how it looks like assembled, lots of wires:

Installing the OS + PhonieBox software

Here, I would direct you to the official PhonieBox installation docs. It guides you through formatting the SD card, setting up SSH access and so on. There are some specifics, so read the fine print as well.

Your installation choices will vary based on your Pi version and network setup. I have not set up any WiFi or WiFi AP, since the Pi 1 does not have any WiFi capabilities built-in. Instead, I'm using a good old Ethernet cable to connect to the Pi when I need to.

On the Raspberry Pi 1 the installation took a long time, I think around an hour or so. If you've botched something during installation, just delete the ~/RPi-Jukebox-RFID folder and try again. Worked for me.

Uploading your music

When I want to add some music to the jukebox, I take it out of its box and connect it with an Ethernet cable. Then I can copy the files over with rsync and manage it via its WebUI accessible on its LAN IP.

Here is the command to copy over everything in episodes folder to the zverinice folder on the Pi:

# replace <username> and <IP> with your username and IP of the jukebox
rsync -avz --progress episodes/ <username>@<IP>:~/RPi-Jukebox-RFID/shared/audiofolders/zverinice/

I had a bit of trouble finding where to upload the files to. You can create music folders at ~/RPi-Jukebox-RFID/shared/audiofolders/ and playlists go to ~/RPi-Jukebox-RFID/shared/playlists/.

It's always a fun family activity when we add new files to the jukebox. My wife is responsible for putting the cards into sleeves together with the name and a drawing of the music/episode and sealing them, then my kid is responsible for booping the cards on the card reader, so that I can pair it to the correct music/episode on the PhonieBox WebUI.

When using the WebUI on an under-powered device like the Raspberry Pi 1, give it some time and be patient. This can be especially visible when listing the files in the audiofolders folder. The first load takes time, but after that, subsequent requests are much faster.

The playback on the Pi 1 is instant, so overall I don't regret using the old Pi.

Putting it into a nice box

When we were building it this year in August, I didn't know if this is something that my kid is going to use or not, so we just took a simple box and put everything in there. I've then asked my kid to paint it as he wants, all I did was add the indication of where to press the cards.

Here is the final result:

Next steps

You'll notice that our version of the PhonieBox has no buttons. Not all PhonieBoxes are built the same. Check out the Calendar section on the project page. There is a huge variety of them.

I first wanted to build a super simple version, to see if it works, how well it works, how much usage it will get and so on.

That said, our version is not so bad either. The JBL speaker has built-in buttons for volume control; though I was sad that the play/pause button is not getting picked up on the Pi. Still, nothing an extra RFID card can't fix. We also have cards for Previous and Next song, Shuffle, Stop and so on, but they are rarely used.

I also bought a rotary encoder for volume control and I have some mechanical keyboard switches lying around that I can use for buttons, so that will probably happen once I decide to create a better box for it.

Conclusion

There are lots of nicer jukeboxes out there, but this one is completely ours! We built it and we're proud of it.

It works completely offline, does not track us, has no ads and we have 100% control over what we can or can't listen to on it. Building it was so much fun and took us less than one afternoon. My kid was very engaged in the process and helped me throughout.

Thanks to the great PhonieBox software that makes this possible.

Declarative Incus on NixOS with SSO

2025-09-29T00:00:00.000Z

I've started my HomeLabbing journey with Proxmox quite a few years ago, thinking I would have many VMs and LXC containers doing so many things. In the end I've ditched Proxmox for NixOS, I'm using one server and many baremetal systemd services. I run 75 of those and only 3 containers. I've yet to use LXC containers.

But lately I've been itching for some gaming and I've got nothing to game on! I've previously used QEMU and Virsh to setup a VM with GPU passthrough on my server and it was working nicely. I was able to connect a monitor the GPU and sit down to game.

But since then another kid came into the picture and I lost that space and had to move to another room. I haven't really had time to game so that was fine. And I started to use my GPU for my Home Assistant's Speech-To-Text functionality via wyoming-piper.

So now I can't dedicate the full GPU to my VM anymore, and neither can I just connect the monitor to the server, since it's now in another room.

I did a bit of searching and found out that if you have an LXC container, it can share the GPU with other processes or even other LXC containers!

Then I found this guide and decided to implement it.

But since I have no Proxmox, I had to look for alternatives, and that is how I found out about Incus. So that is what I'll be showing you how to set it up on your NixOS machine with SSO login via Authelia.

Phew, what an intro. Let's get started!

Prerequisites

This guide assumes you already have Caddy and Authelia configured.

My Incus NixOS module

This post will be a bit different in the sense that I will just provide you with the NixOS module that I use. I will try to comment it extensively, so that you know what values to put where for your setup.

What you don't see in this module is how I set up Caddy and Authelia, both of which this module uses. If you run into issues, I'll be happy to help you out if you reach out (my email is on the homepage).

You might need the following pages to help you if you get stuck, they sure helped me tremendously:

Keep in mind that whoever can log into Incus can do everything. They do not yet have a concept of users or permissions. A bit of a shame to be really honest.

Anyway, here is the whole thing:

{
  config,
  lib,
  ...
}:
# This uses a modified standard lib that includes a `my` field for my-setup-specific values.
with lib;

let
  # For this config, for easier reference
  cfg = config.my.services.incus;
  # Module option `dataDir` is the root dir, so we expand it a bit to get the storage pool dir
  # Down the line I might need more than one
  defaultStoragePoolDir = "${cfg.dataDir}/storage-pools/default";
  # The OIDC Client ID I will use. You should make this a bit longer, and a bit more random than this example
  oidcClientId = "incus";
in
{
  # Here we define the available options consumers of this module can set
  options.my.services.incus = with lib.types; {
    enable = mkEnableOption "incus";

    # I place all my data in `/var/my`, so incus gets a place there too
    dataDir = mkOption {
      type = path;
      default = "/var/my/incus";
    };

    # The LISTEN address for the UI
    uiAddress = mkOption {
      type = str;
      default = "127.0.0.1";
    };

    # And its corresponding port
    uiPort = mkOption {
      type = int;
      default = 17171;
    };

    # The domain name to use
    # Don't forget to create this domain name on your router or wherever you create those
    domain = mkOption {
      type = str;
      default = "incus.${my.domain}"; # expands to something like `incus.example.com`
    };

    # The network Incus will use for containers
    # We'll create a bridge, so a `br` is in the name
    networkName = mkOption {
      type = str;
      default = "incusbr0";
    };
  };

  # Apply config only if the module is enabled
  config = mkIf cfg.enable {
    virtualisation.incus = {
      # Enable Incus
      enable = true;
      # Enable the UI
      ui.enable = true;
      # Specify the initial settings
      # Mind that if you change these imperatively via the `incus` command, they will not be overwritten by this declarative configuration.
      preseed =
        let
          poolName = "default";
        in
        {
          config = {
            # Where the UI will listen on
            "core.https_address" = "${cfg.uiAddress}:${toString cfg.uiPort}";
            # OIDC config
            "oidc.issuer" = "https://${config.my.services.authelia.domain}"; # This resolves to something like `https://authelia.example.com`
            "oidc.client.id" = oidcClientId;
            "oidc.audience" = "https://${cfg.domain}";
            # I went the SSO route, since I use that everywhere else as well
            # This disables certificate login
            "user.ui.sso_only" = "true";
          };
          networks = [
            {
              # VMs and containers will have IPs in the 10.10.10.X network
              config = {
                "ipv4.address" = "10.10.10.1/24";
                "ipv4.nat" = "true";
              };
              # Name the network
              name = cfg.networkName;
              # Specify its type
              type = "bridge";
            }
          ];
          # The profiles are the default settings for containers
          profiles = [
            {
              # Name this profile
              name = "default";
              devices = {
                # The network that will get attached to our container, that will use our bridge
                eth0 = {
                  name = "eth0";
                  network = cfg.networkName;
                  type = "nic";
                };
                # Create a disk mounted at root, using the 'default' pool (created below)
                root = {
                  path = "/";
                  pool = poolName;
                  type = "disk";
                };
              };
            }
          ];
          # Define the data pool, with the 'dir' driver, meaning it's just a directory at 'config.source'
          storage_pools = [
            {
              config.source = defaultStoragePoolDir;
              driver = "dir";
              name = poolName;
            }
          ];
        };
    };

    # Add my user to these groups so that it can use and configure Incus
    my.user = {
      extraGroups = [
        "incus"
        "incus-admin"
      ];
    };

    # As per the Wiki, Incus only works with nftables, so we enable that
    networking.nftables.enable = true;
    # And set the bridge to be trusted to allow traffic on this interface
    networking.firewall.trustedInterfaces = [ cfg.networkName ];

    # Create the folder if it does not exist
    systemd.tmpfiles.rules = [
      "d ${defaultStoragePoolDir} 750 root root"
    ];

    # This one uses the Impermanence module, skip it if you don't use it
    # Set the data and config directories to persist across reboots
    my.persisted.directories = [
      cfg.dataDir
      "/var/lib/incus"
    ];

    # Make it accessible
    my.services = {
      proxy.reverseProxies = [
        {
          from = cfg.domain;
          extraConfig = ''
            reverse_proxy https://${cfg.uiAddress}:${toString cfg.uiPort} {
              transport http {
                tls_insecure_skip_verify
              }
            }
          '';
        }
      ];
      # Above translates into this Caddy virtual host config
      # services.caddy.virtualHosts."${cfg.domain}" ={
      #  extraConfig = ''
      #    forward_auth ${config.my.services.authelia.domain} {
      #      uri /api/authz/forward-auth
      #      copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
      #    }
      #
      #    reverse_proxy https://${cfg.uiAddress}:${toString cfg.uiPort} {
      #      transport http {
      #        tls_insecure_skip_verify
      #      }
      #    }
      #  '';
      #  hostName = cfg.domain;
      #  useACMEHost = my.domain;
      #}

      # This sets up Incus in Authelia
      # Again this uses my module
      authelia = {
        # This one is merged into `config.services.authelia.instances.default.settings.access_control.rules`
        accessRules = [
          {
            domain = cfg.domain;
            subject = [
              [ "user:luka" ]
            ];
            whenInternal = true;
            policy = "two_factor";
          }
          # becomes
          #{
          #  domain = cfg.domain;
          #  networks = "internal"; # I only want Incus to be accessible on my internal networks (my LAN, LAB, VPN, etc)
          #  policy = "two_factor";
          #  subject = [ [ "user:luka" ] ];
          #}
        ];
        # This one is simply mapped
        # config.services.authelia.instances.default.settings.identity_providers.oidc.clients = cfg.oidcClients;
        oidcClients = [
          {
            client_id = oidcClientId;
            client_name = "Incus";
            public = true;
            authorization_policy = "two_factor";
            require_pkce = false;
            pkce_challenge_method = "";
            redirect_uris = [
              "https://${cfg.domain}/oidc/callback"
            ];
            audience = [
              "https://${cfg.domain}"
            ];
            scopes = [
              "openid"
              "offline_access"
            ];
            response_types = [
              "code"
            ];
            grant_types = [
              "authorization_code"
              "refresh_token"
            ];
            access_token_signed_response_alg = "RS256";
            userinfo_signed_response_alg = "none";
            token_endpoint_auth_method = "none";
          }
        ];
      };
    };
  };
}

And there we go! Don't forget to git add modules/incus.nix and my.services.incus.enable = true; in your hosts configuration and save. Just one nixos-rebuild later and you're good to go!

Conclusion

So I have Incus running now and I was able to experiment with it already. But I still have not yet set up a headless gaming LXC container. Perhaps in another blog post.

Setting up your own VPN server

2025-09-28T00:00:00.000Z

At work, we've had to come up with a way to access devices hiding behind firewalls at a few different locations. This is a great fit for a VPN.

Let's explore how to set up a manageable private VPN in the public cloud. We'll leverage podman and systemd to manage a container.

The plan

We'll use WireGuard as our VPN solution, it's fast, simple, modern and secure, and manage it with wg-easy.

Caddy will provide TLS certificates to secure our frontend.

You'll also need a domain.

Setting up the VM

You can use any public cloud provider you want. You don't need a powerful VM for a VPN, so a cheap one will do just fine.

This guide focuses on Debian-based systems (specifically Ubuntu), as that's what we used. So if you want to follow along select that.

Once the VM is running, note its IP and update your DNS records to point to the machine. Add the following DNS entries to wherever you have those:

an A record e.g. vpn.example.com with your VMs IP
a CNAME record for wg-easy frontend, e.g. wg-easy.example.com or wg-easy.vpn.example, in either case it should point to vpn.example.com
- you could also skip this second domain if all you'll host on this VM is the wg-easy frontend, if you do, remember to use vpn.example.com in your Caddyfile later.

Some cloud providers set up the SSH access keys for you, but if they don't, open a web console, edit ~/.ssh/authorized_keys and paste in your SSH key. Now you can use regular SSH to connect to the machine.

First make sure SSH server does not allow password login, by inspecting the config at /etc/ssh/ssh_config and setting PasswordAuthentication no if its not set already.

Then you should update it:

apt update
apt upgrade

And install the dependencies we'll need:

apt install -y podman caddy

Firewall setup

You'll need to allow certain ports:

Protocol	Type	Port	Source
SSH	TCP	22	All IPv4
HTTP	TCP	80	All IPv4
HTTPS	TCP	443	All IPv4
WireGuard	UDP	51820	All IPv4

Installing wg-easy

Usually I would advocate for installing it as a pure systemd unit with a binary run as a dynamic/service user, but wg-easy does not have that option. They only support deploying via a container.

So we'll follow their guide here and modify it a bit for our needs.

# Create folders for our files
mkdir -p /etc/containers/systemd/wg-easy
mkdir -p /etc/containers/volumes/wg-easy

We modified the container file a bit to drop the IPv6 stuff, since some of our ISPs don't have that yet (I know!). So we also don't need the network.

As per the guide above, we'll define our container using a .container file. This is a feature of Podman's quadlet generator, which allows systemd to manage containers directly from a simple definition file. Its structure is the same as it is for regular systemd unit files.

# /etc/containers/systemd/wg-easy/wg-easy.container
[Container]
ContainerName=wg-easy
Image=ghcr.io/wg-easy/wg-easy:15
AutoUpdate=registry

Volume=/etc/containers/volumes/wg-easy:/etc/wireguard:Z
PublishPort=51820:51820/udp
PublishPort=51821:51821/tcp

# Disable IPv6, as some ISPs don't have full support yet.
Environment=DISABLE_IPV6=true

AddCapability=NET_ADMIN
AddCapability=SYS_MODULE
AddCapability=NET_RAW
Sysctl=net.ipv4.ip_forward=1
Sysctl=net.ipv4.conf.all.src_valid_mark=1

[Install]
WantedBy=default.target

We indicate that we want additional modules loaded with the following file:

# /etc/modules-load.d/wg-easy.conf
wireguard
nft_masq

You can load these modules with either a reboot of the VM or by running systemctl restart systemd-modules-load.service.

Then we can start the service:

systemctl daemon-reload
systemctl start wg-easy

Verify that the service is running with systemctl status wg-easy.

Setup Caddy

For setting up Caddy all we need is a Caddyfile.

# /etc/caddy/Caddyfile
wg-easy.vpn.example.com {
	reverse_proxy localhost:51821
}

Then reload the service and check that all is good:

systemctl reload caddy
systemctl status caddy

You can also inspect the logs and check that it got the TLS certificates with journalctl -eu caddy.

Verify we can access wg-easy by going to https://wg-easy.vpn.example.com.

I strongly urge you to set up 2FA on the wg-easy frontend, especially if you'll be exposing it on the WWW.

Configure WireGuard via `wg-easy`

The configuration will depend on your specific needs. This setup is highly flexible, allowing you to connect single devices or entire networks.

But there is one last step that you should do according to the linked guide and that is to update the hooks. You can find these in the Administrator > Admin panel > Hooks.

PostUp hook:

nft add table inet wg_table;
nft add chain inet wg_table prerouting { type nat hook prerouting priority 100 \; };
nft add chain inet wg_table postrouting { type nat hook postrouting priority 100 \; };
nft add rule inet wg_table postrouting ip saddr  oifname  masquerade;
nft add chain inet wg_table input { type filter hook input priority 0 \; policy accept \; };
nft add rule inet wg_table input udp dport  accept;
nft add rule inet wg_table input tcp dport  accept;
nft add chain inet wg_table forward { type filter hook forward priority 0 \; policy accept \; };
nft add rule inet wg_table forward iifname "wg0" accept;
nft add rule inet wg_table forward oifname "wg0" accept;

This configuration enables the WireGuard server to:

Accept VPN connections
Route client traffic to the internet (NAT/masquerade)
Allow forwarding between the VPN and other networks
Accept management interface connections

PostDown hook:

nft delete table inet wg_table

Then, go to Admin panel > General and make sure that the Host and the Port are correct.

I've set the AllowedIPs to 10.99.0.0/16. This is the global default setting that will get set for all clients. It tells the clients what traffic to route into the VPN. You would set this to 0.0.0.0/0, if you'd like to route all traffic through the VPN.

I've used same IP in Admin panel > Interface > Change CIDR > IPv4. This defines the WireGuard subnet.

Now you can add your first client.

Click the New button on the dashboard, give client a name and an (option) expiration date. If you open up the client by clicking on its name you can see that an IP from the WireGuard network has been allocated to it. I will change this one to 10.99.1.1 for my scheme.

The AllowedIPs is here if we want to override the default from the Admin panel.

The ServerAllowedIPs needs to be filled out if we want the server to route traffic to this client (or the network connected to it). I foresee that I will want to route more than just the client IP to this client (for its network), so I will input 10.99.1.0/24 here.

When you're done, wg-easy makes it simple to share the client config to each client with either a QR code, a file or a link.

Testing the connection

Downloading the config file for my client, I import it into my WireGuard client installed on my machine and turn it on. If everything works, you will see that a handshake has happened and on the wg-easy dashboard you will see that some data has started flowing through the VPN.

Next steps

Security hardening

use a separate non-root user for the service
restrict the firewall even further (e.g. to allow connections only from specific IPs)

Ad blocking

You can add some DNS-based Ad blocking, like the excelent Pi-hole.

Monitoring and Alerting

You might want to set up monitoring and alerting to see how much traffic, bandwidth, CPU or RAM you're using.

Automate the provisioning process

At work we wrapped this process up in a script to make it painless to deploy this setup to another machine, if needed. If you'll add more than just a few services, then going with Ansible or Terraform might be a better fit.

Conclusion

We saw how easy it is to set up your own and private VPN server, that you can easily share with your friends and family. It runs on a cheap public cloud VM that is cheaper than leading hosted VPN solutions.

Try it out and let me know how well it works for you

My hardware

2025-09-19T00:00:00.000Z

I have lots of little machines! This post will describe them and what I use them for. Let's go!

The Server

This is my crown jewel custom-built box.

It runs most of my services; it is my cloud (NextCloud), password manager (Vaultwarden), git forge (Forgejo), media server (the *arrs and Plex), and lots and lots more.

Here are the specs:

CPU: AMD EPYC 7402P 24-Core Processor
- Usage varies, usually under 10%, but NixOS rebuilds, Plex transcoding, and running local LLMs stress it quite a lot
RAM: 128GB DDR4 running at 3200MHz
- All 8 memory slots are populated with 16GB sticks
- Currently using ~10GB with 115GB available, but this varies as I play with local LLMs
GPU: NVIDIA GeForce GTX 1070 8GB VRAM
- Currently using ~3GB for STT for my HomeAssistant Voice Control
DELL Perc H310 SAS Raid Controller
- For connecting all the storage devices
Network:
- 2x Intel I210 Gigabit Ethernet controllers

It's a beefy machine, but if I were to buy it again, I would go for the 16 core EPYC. I only chose the 24 core one because it was just 20eur more expensive compared to the 16 core one. But it does draw more power, which results in more heat generated, which sucks in the summer.

Anyway, I love running heavy loads on it and watching all the cores light up. Nix updates and rebuilds sometimes rebuild a lot of packages, and this machine handles it like a champ.

What is great about having the server motherboard is having IPMI! I never saw the appeal of connecting to the machine and having the ability to change BIOS settings remotely, for example, but after some failed updates that locked me out of SSH, I was able to connect the machine via a web console and restore connectivity, it was great! I recommend getting a motherboard with IPMI now.

Another great thing is having two NICs. I can assign one to a VM or something else.

Storage

I have two BTRFS pools, one for OS and services and another for media. Both are set to RAID1, so I generally buy two drives if I want to expand my storage.

I've had one drive fail and I was able to replace it with no data loss. I have scheduled data scrubs and they have at times detected and corrected issues. It's also quite fast, especially if you split the spinning drives and SSDs.

All in all, I recommend using BTRFS.

Root pool

My root pool is a mishmash of old drives that I cannibalized from other/older systems, e.g. my defunct gaming PC.

Devices:

NVMe SSD: WDC WDS500G2B0C (500GB)
SATA SSDs:
- Crucial CT512MX100SSD1 (512GB)
- Samsung 870 EVO (1TB)

This gives me ~1TB of usable storage.

So far it has performed quite well and no devices have died so far.

Media pool

Here is the place for my big files and (local) backups.

Media pool Hard Drives:

2x Seagate ST12000NM0127 (12TB each)
2x Seagate ST8000NE001 (8TB each)
2x WD WD60EFRX/EFAX (6TB each)
1x WD WD30EFRX (3TB)
1x WD WD20NMVW (2TB external, for backups)

Here I've lost one 3TB drive to failure in the last 5 years. I was able to replace it and the BTRFS pool carried on with no data loss.

PC-Engines APU2 board

I have a PC-engines APU2 board.

Currently its serving as my main router with OPNsense. I manage my DHCP, DNS, VPNs, VLANs and other network related things on it.

So far it's been great, though the CPU usage frequently reaches 100% and it's also running quite hot.

Linksys EA7500

This one serves as my main home Wi-Fi AP running OpenWrt.

It has been with me for the longest time, even before I started my HomeLab journey and I only needed it for WiFi.

NVidia Shield

This is a relatively new addition, I bought it used to replace the apps of my smart LG TV. The TV Plex app was slow and I was also afraid I would start to get ads on the TV at some point via a sneaky WebOS update.

With the addition of the NVIDIA Shield, I was able to disconnect the TV from the network and now I only use it as a TV screen.

Raspberry Pi 1

Just recently I used it to create a Phoniebox.

I should write a guide on how to build it yourself. It was super easy, literally took me minutes.

Since it does not have a Wi-Fi, I can't actually check the load its under (I could connect to it via Ethernet cable, but I'm lazy and can't be bothered right now). Interacting with it with the RFID cards is working great and feels snappy.

Overall, it's working great for such an underpowered device.

Dell Wyze 5070

This little machine is currently running my HomeAssistant instance. It has 4GB of RAM.

The instance is working great, it loads fast and the devices it controls are very responsive. It is currently connected to 18 smart home devices, most of which are lights and switches.

Load on the CPU rarely reaches 10%, its usually under 4%, so there is a lot of room for growth. It currently consumes around 1.3GB of RAM.

The closet

I also have a few other machines that are not in use right now.

Raspberry Pi 5

This was an impulse buy, I admit. I think I was going to put some retro gaming OS on it, then I was gonna turn it into a monitoring solution for my HomeLab and now it's sitting and gathering dust.

We'll see what use I find for it down the road.

My old gaming rig

This one is based around a Asus Z170 Pro Gaming motherboard.

I think it has an i5 processor and 16GB of RAM. At some point I used it as a temporary server replacement, when my main server motherboard died. It was a painless switch, but I remember the slowness and I think the network wasn't the most stable.

Anyway, it's gathering dust now as well. I keep intending on selling it, but just never get around to it.

Caching adventures with Caddy and Nix

2025-08-08T00:00:00.000Z

So if you've followed along my Create a static blog with Nix blog post you might have noticed an issue when serving the files.

When you update a blog post and deploy it to the server, you check it on your phone to see the new changes, but they are just not showing! You have to do a hard-refresh for them to show up. You investigate and notice that the server is always returning 304 Not Modified for all static files. You try creating a new blog post, just to test it out, and you get 200 response with the content of the post just fine. You refresh the page, you get a 304 which is also fine - you think caching is working. You then update the blog post and expect a 200 response with the content, but you still get a 304 Not Modified response with no content. Browser then displays the old blog post. Weird. Something is not working as it should.

Let's investigate.

How browser caching works

Say we're serving a static file /index.html. When you first navigate to this page, browser makes a request for that file and displays it. It also saves it to its own cache so that it does not have to fetch it everytime you open that page, saving you time and bandwidth.

But if the file changes on the server, how does browser usually display the new content?

When a browser navigates to a page for the second time (or any subsequent visit), it includes an If-Modified-Since header in its request. This header contains the Last-Modified timestamp that the server provided during the initial request.

Upon receiving this request, the server compares the header timestamp with the file's actual modification time. If the file has been modified since the indicated time, the server responds with the complete file. If no changes have occurred, it returns a 304 Not Modified status code.

When browser receives the full file, it displays the content, updates its cache, and records the new timestamp for future requests. If it receives a 304 response, it simply displays the cached version of the page.

That works great, if the server has proper file modification timestamps on the files it serves. That is not the case for files in the nix store.

Nix's peculiarities strike again

When Nix adds a file to the /nix/store, it strips away the file modification times.

Let's take a look at a file in the store:

❯ ls -l /nix/store/50n81h7r3mp2v8ybjc7qrjx5igrcghmc-just-1.42.3/bin/just
-r-xr-xr-x 1 root nixbld 3.7M Jan  1  1970 /nix/store/50n81h7r3mp2v8ybjc7qrjx5igrcghmc-just-1.42.3/bin/just*

❯ stat --format %y /nix/store/50n81h7r3mp2v8ybjc7qrjx5igrcghmc-just-1.42.3/bin/just
1970-01-01 01:00:01.000000000 +0100

❯ stat --format %Y /nix/store/50n81h7r3mp2v8ybjc7qrjx5igrcghmc-just-1.42.3/bin/just
1

❯ stat --help | rg "(format=|modif)"
  -c  --format=FORMAT   use the specified FORMAT instead of the default;
  %y   time of last data modification, human-readable
  %Y   time of last data modification, seconds since Epoch

You can see that the modification time is one second after the Unix epoch.

This is clearly an issue for our Caddy server. When the If-Modified-Since time is always after the file's modified time, Caddy will consistently return a 304 Not Modified response for requests containing the If-Modified-Since header.

This behavior is actually correct - Caddy is operating according to specification.

So what can we do?

Well, if browser does not have the last modification time, it won't send the If-Modified-Since header and Caddy will return the whole file always. Which does fix our issue of updates not being seen by people, but also wastes bandwidth and increases load times. Not cool.

When searching for this I encountered ETags. ETag stands for Entity Tag. You can think of them as file hashes. If a file changes, so does its hash.

Browsers can use this for cache control via the ETag header.

In my tests I found that Caddy would not generate etags for my files. After some searching I confirmed it when I found this PR: fileserver: Don't set Etag if mtime is 0 or 1. Remember when we inspected the modification times in the nix store? Yeah, its 1.

So Caddy won't do it automatically, but can we somehow force it? We can!

The file_server module accepts etag_file_extensions, an array of extensions from which ETags will be read by Caddy. So for each file we'll just have to create an ETag file.

Alright, so we have a plan!

Implementation time

Let's first generate the ETag files.

Generating ETag files

We add some additional build inputs (fd and coreutils for md5sum and cut) and generate the files as part of our installPhase.

diff --git a/flake.nix b/flake.nix
index d8c6552..d1b602f 100644
--- a/flake.nix
+++ b/flake.nix
@@ -30,12 +30,22 @@
           pname = "my-static-site";
           version = "1.0.0";
           src = ./.;
-          buildInputs = [ eleventy ];
+          buildInputs = with pkgs; [
+            eleventy
+            fd
+            coreutils
+          ];
           buildPhase = "eleventy";
           installPhase = ''
             mkdir -p $out/
             echo $out
             cp -r _site/* $out/
+
+            # Generate .etag files for cache validation
+            for file in $(fd --type f . "$out"); do
+              hash=$(md5sum "$file" | cut -d" " -f1)
+              echo "\"$hash\"" > "$file.etag"
+            done;
           '';
         };
       in

If you wan't you can swap out the md5sum for something faster/slower, in the end it just has to be uniqu enough.

Alright lets test it out with nix build and inspect the results:

❯ nix build
warning: Git tree '[...]/create-a-static-blog-with-nix' is dirty

❯ tree ./result
./result
├── index.html
└── index.html.etag

1 directory, 2 files

❯ cat ./result/index.html.etag
"5273e1f62e43bab55701f318492d7cad"

Important: The contents of the .etag file have to be quoted for this to work. I pulled my hair out until the kind folks at the Caddy helped me solve the issue.

Configuring Caddy

Now that we have the ETag files, lets tell Caddy to use them.

So we need to remove the Last-Modified header, to force browser to use ETags and specify the file extension Caddy should use to get the ETags for our files.

diff --git a/nixos-configuration/my-static-site.nix b/nixos-configuration/my-static-site.nix
index 82737c4..650898a 100644
--- a/nixos-configuration/my-static-site.nix
+++ b/nixos-configuration/my-static-site.nix
@@ -7,7 +7,12 @@ in
     enable = true;
     # Needs `http://` prefix so that it does not try to request TLS certificates and redirect to 443
     virtualHosts."http://${site-url}".extraConfig = ''
-      file_server
+      header {
+        -Last-Modified
+      }
+      file_server {
+          etag_file_extensions .etag
+      }
       root * ${inputs.our-site.packages."${pkgs.system}".default}
       encode gzip
     '';

Now is a good time to commit this: Use ETags instead of Last-Modified for caching.

ETag browser caching process

With ETags properly configured, browser caching process follows this sequence:

Initial Request: The server retrieves the ETag from the index.html.etag file and includes it in the response headers alongside the index.html content. Browser receives both the file and its corresponding ETag value, caching them together.

Subsequent Requests: When browser requests the same file again, it automatically includes an If-None-Match header containing the previously cached ETag value. The server compares this ETag against the current value stored in index.html.etag. If they match, the server responds with a 304 Not Modified status, allowing browser to use its cached version. If the ETags differ, the server sends the updated file with the new ETag.

That's it, we fixed it!

This was one of those frustrating debugging sessions where everything seemed to be working correctly - Caddy was following HTTP specifications to the letter, browsers were caching as expected, and yet we couldn't see updates. The real culprit turned out to be Nix's timestamp normalization, a detail of how the Nix store works.

What made me miss this issue in the first place is that it only manifested for me after making some updates to my posts. But with some persistence we found a clean solution using ETags that, in my opinion, works better than modification times anyway.

Now our static site updates show up immediately for users, without sacrificing caching performance. Problem solved!

Create a static blog with Nix

2025-07-02T00:00:00.000Z

This blog has been written with Eleventy. It handles the static site generation part, like converting markdown to HTML, routes and so on. Classic static site generator stuff. Their slogan is "Eleventy is a simpler static site generator" and so far I think it lives up to it.

What I don't like about it is that you need to install Node.js on your machine to get it to work. I seriously considered using Zola instead for this reason alone. In the end I decided for Eleventy because it's more mature and has a bigger community. The documentation is also more complete I feel.

If you want to skip ahead and take a look at the resulting repository, you can find it at tech-blog/create-a-static-blog-with-nix.

Also, there is also a continuation of this post in Caching adventures with Caddy and Nix. It's where we investigate the (tricky) caching issues with this setup and fix them.

Bootstrapping the project

So, given that I decided to go with Eleventy, that means we need to have Node.js installed. I don't want to have it installed system-wide just for Eleventy to work, so I decided to reach for the power of Nix.

To be fair, I would've used Nix even if I went with some other static site generator, but using something like Eleventy means I get to learn how to use Node packages with Nix.

First step is creating a git repository (git init) and a new flake (nix flake init). I like to use flake-utils, so I add that to the inputs and adjust the flake to use it. Run nix flake update to get the flake.lock file and then let's do an initial commit (git add . && git commit -m "Initial commit").

Now we have a good starting point.

Commit: Initial commit

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs =
    {
      self,
      nixpkgs,
      flake-utils,
      ...
    }@inputs:
    flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in
      {
        devShells.default = pkgs.mkShell {
          buildInputs = [];
          shellHook = "";
        };
      }
    );
}

Development shell

Next step I always do is add a development shell.

If you're not familiar with that, here is a nice write up (I will use nix develop). But the short summary is that it provides a sort of virtual environment with the tools you need to interact with the project. It is super simple for other people to use and I think it is way better than using docker/podman for sharing development environments.

I just can't live without just, the task runner. I always use it to run tasks in the project, but not everyone has it installed.

# This command will output the path of the just command if you have it installed
❯ which just
/Users/luka/.nix-profile/bin/just

You can see I already have it installed system-wide, but I always try to include all project dependencies in my development shell, just in case anyone else wants to interact with the project.

Let's modify the flake.nix to add it.

diff --git a/flake.nix b/flake.nix
index 58dadad..fffb25c 100644
--- a/flake.nix
+++ b/flake.nix
@@ -18,7 +18,9 @@
       in
       {
         devShells.default = pkgs.mkShell {
-          buildInputs = [];
+          buildInputs = with pkgs; [
+            just
+          ];
           shellHook = "";
         };
       }

Now, we have to activate the development shell. We can do that by running nix develop.

❯ nix develop
[...]
❯ which just
/nix/store/w0s0f89zcpwl9ipygxiihba0j6fgwnyq-just-1.40.0/bin/just
❯ #press CTRL+D to exit this development shell or run exit command
exit

❯ which just
/Users/luka/.nix-profile/bin/just

As you can see above, we get a just binary, that is exactly defined by the nixpkgs commit our flake.lock is pinned to. When you update the flake (nix flake update) your project binaries will also update. In my case the binary provided by the system and the one provided by the development shell one are the same, but that will not always hold.

One thing you might've noticed if you're using zsh is that the new shell is pure bash. Use nix develop -c $SHELL to retain your shell instead.

Anyway, now, when you want to work on your blog/project, you need to cd into the project root and run nix develop. If you're using the excellent direnv, you can also paste use flake in your .envrc, run direnv allow and now whenever you cd into this repo, you'll get dropped into the development shell automatically.

Now let's run just --init to create a justfile and edit to something like:

# The default command to run when ran with just 'just'
[group('General')]
default: help

# Print the available commands
[group('General')]
help:
    @just --list

# Update project dependencies
[group('General')]
update:
    nix flake update

Now when you run just you get a nice list of available recipes you can choose from.

❯ just
Available recipes:
    [General]
    default # The default command to run when ran with just 'just'
    help    # Print the available commands
    update  # Update project dependencies

I think it's time we commit these changes and work on getting Eleventy into our development shell.

Commit: Add just and justfile

Add Eleventy

Now here comes the tricky part. We need to add Eleventy to our project dependencies.

As mentioned earlier, I don't really want to install Node.js to my machine, so let's see if we can find Eleventy in Nixpkgs repository and use that instead. Searching nixpkgs for the Eleventy package, we find nothing (as of 2025-06-22 at least). What now?

Well, we can package it ourselves and add it to our repository as a dependency that way. This being Nix, it took me quite a while to figure out how to do all of this. But I persevered, because that is what I do and I like doing things the hard way I guess. Anyway after a few hours of searching the web and scouring the nixpkgs source code here is what I came up with.

I found the pkgs.buildNpmPackage function (source). It seems like a perfect candidate for us to use. To build the NPM package it needs its source code, so let's get that first.

You do that by adding it as an input to our flake. All inputs are git repositories and Nix manages them for us.

diff --git a/flake.nix b/flake.nix
index fffb25c..18aea66 100644
--- a/flake.nix
+++ b/flake.nix
@@ -2,6 +2,11 @@
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
     flake-utils.url = "github:numtide/flake-utils";
+    eleventy-src = {
+      url = "github:11ty/eleventy";
+      flake = false;
+    };
+
   };

   outputs =

Since the Eleventy repository does not contain a flake, you need to set flake = false;.

Now let's pass that to buildNpmPackage to build it for us. Let's create a pkgs folder and place a 11ty-eleventy.nix file there with the following contents:

# We'll pass in the pkgs and `src`
{ pkgs, src }:
pkgs.buildNpmPackage {
  # Package name
  pname = "eleventy";
  version = "1.0.0";
  src = src;
  npmDepsHash = pkgs.lib.fakeHash; # We'll replace this soon
  dontNpmBuild = true;
  meta = with pkgs.lib; {
    description = "A simpler static site generator";
    homepage = "https://www.11ty.dev/";
    license = licenses.mit;
  };
}

We set dontNpmBuild to true because the package.json in the Eleventy repository does not contain a build script.

And use it in our flake.nix:

diff --git a/flake.nix b/flake.nix
index 18aea66..58dd8c7 100644
--- a/flake.nix
+++ b/flake.nix
@@ -20,6 +20,10 @@
       system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
+        eleventy = import ./pkgs/11ty-eleventy.nix {
+          inherit pkgs;
+          src = inputs.eleventy-src;
+        };
       in
       {
         devShells.default = pkgs.mkShell {

Make sure that you stage the changes with git (git add .), otherwise you'll get an error that [...]source/pkgs/pkgs/11ty-eleventy.nix' does not exist when Nix tries to use it.

Cool, now we have everything set up, all we need is to expose it in our outputs.

diff --git a/flake.nix b/flake.nix
index 58dd8c7..e45810f 100644
--- a/flake.nix
+++ b/flake.nix
@@ -26,6 +26,7 @@
         };
       in
       {
+        packages.eleventy = eleventy;
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
             just

nix flake show command shows us the outputs of our flake. I've edited it for brevity a bit, but yours should look similar. We can see that we have one devShell (default) and one package (eleventy).

❯ nix flake show
warning: Git tree '[...]/create-a-static-blog-with-nix' is dirty
git+file://[...]/create-a-static-blog-with-nix
├───devShells
│   ├───aarch64-darwin
│   │   └───default: development environment 'nix-shell'
[...]
└───packages
    ├───aarch64-darwin
    │   └───eleventy: package 'eleventy-1.0.0'
[...]

Now let's try and build it.

❯ nix build .#eleventy
warning: Git tree '[...]/create-a-static-blog-with-nix' is dirty
error: hash mismatch in fixed-output derivation '/nix/store/kx4k4fh0hh7v0apnxc9xrnca6g71nwrh-eleventy-1.0.0-npm-deps.drv':
         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
            got:    sha256-LGdCM1gjt3hRn7BiIlbA4e2HOiQ6e/qkAtWp0Qwn+PE=
error: 1 dependencies of derivation '/nix/store/cbc08ym28sgzz123gjf06q0k26j2sxc1-eleventy-1.0.0.drv' failed to build

If you've followed along this is what you should see, just the hashes will be different. We expected this error to happen, since we used a fakeHash. If we replace the fake hash with the correct one the package should build.

IMPORTANT: You should use the hash that you got, don't copy mine. As you'll get another hash mismatch.

diff --git a/pkgs/11ty-eleventy.nix b/pkgs/11ty-eleventy.nix
index c0692bf..c6adbfa 100644
--- a/pkgs/11ty-eleventy.nix
+++ b/pkgs/11ty-eleventy.nix
@@ -5,7 +5,7 @@ pkgs.buildNpmPackage {
   pname = "eleventy";
   version = "1.0.0";
   src = src;
-  npmDepsHash = pkgs.lib.fakeHash; # We'll replace this soon
+  npmDepsHash = "sha256-LGdCM1gjt3hRn7BiIlbA4e2HOiQ6e/qkAtWp0Qwn+PE=";
   dontNpmBuild = true;
   meta = with pkgs.lib; {
     description = "A simpler static site generator";

Running nix build .#eleventy now completes successfully and gives us a result file in the root of our repo. If we take a look at what it points to, we can see it points at /nix/store/[...]-eleventy-1.0.0.

❯ readlink result
/nix/store/hqa8c57nbl7rlimi1fa611r64lp0mp4w-eleventy-1.0.0

And taking a deeper look at the result, we can see that it contains a binary (result/bin/eleventy) and node_modules.

❯ tree result | head
result
├── bin
│   └── eleventy
└── lib
    └── node_modules
        └── @11ty
            └── eleventy
                ├── cmd.cjs
                ├── CODE_OF_CONDUCT.md
                ├── LICENSE

Let's try executing that binary:

❯ ./result/bin/eleventy --version
3.1.2-beta.2

❯ ./result/bin/eleventy --help | head
Usage: eleventy
       eleventy --input=. --output=./_site
       eleventy --serve

Arguments:

     --version

     --input=.
       Input template files (default: `.`)

Works like a charm! What a great moment.

To get that binary available in our development shell, we need to add the derivation (what Nix calls packages) as a build input. Nix will then add the bin folder of that derivation to our path.

diff --git a/flake.nix b/flake.nix
index e45810f..29adafc 100644
--- a/flake.nix
+++ b/flake.nix
@@ -30,6 +30,7 @@
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
             just
+            eleventy
           ];
           shellHook = "";
         };

Let's enter the shell and try it out:

❯ nix develop

❯ eleventy --version
3.1.2-beta.2

❯ which eleventy
/nix/store/hqa8c57nbl7rlimi1fa611r64lp0mp4w-eleventy-1.0.0/bin/eleventy

We can see it's exactly the same Nix store path as the one we got when we ran nix build .#eleventy.

We could call it quits at this point, but I don't like that the version we specified in the package does not match the actual eleventy version. Another thing that bothers me is that when the eleventy repository updates (and we run nix flake update to get that update), we'll have to manually update the hash to the new one.

Ugh, manual work! I would much rather invest a few more hours into this right now, then ever have to worry about manual work.

Relevant XKCD as always: Is it worth the time?. In my case I think the answer would be a no, but hopefully for you it might be a yes.

Anyway, I had to figure out how this hash is calculated. Turns out there is a package called prefetch-npm-deps that given a package-lock.json file outputs the desired hash. So let's use it to calculate the hash.

Let's create a new justfile recipe called update-eleventy and let's not forget to add the binaries we use in the recipe to our development shell.

diff --git a/flake.nix b/flake.nix
index 29adafc..dd6cc6d 100644
--- a/flake.nix
+++ b/flake.nix
@@ -31,6 +31,9 @@
           buildInputs = with pkgs; [
             just
             eleventy
+            prefetch-npm-deps
+            jq
+            curlMinimal
           ];
           shellHook = "";
         };
diff --git a/justfile b/justfile
index 6776929..c7450cb 100644
--- a/justfile
+++ b/justfile
@@ -11,3 +11,13 @@ help:
 [group('General')]
 update:
     nix flake update
+
+# Update packages sha256 and version
+update-eleventy:
+    #!/bin/bash
+    pkgs=$(pwd)/pkgs
+    cd $(mktemp -d)
+    curl -f https://raw.githubusercontent.com/11ty/eleventy/refs/heads/main/package-lock.json -o package-lock.json
+    prefetch-npm-deps package-lock.json > $pkgs/11ty-eleventy.sha256
+    cat package-lock.json | jq --raw-output ".version" > $pkgs/11ty-eleventy.version
+

Let me explain the update-eleventy recipe, line by line:

#!/bin/bash
- this tells Just to interpret this recipe as a bash script
- this is significant, since otherwise Just executes each line in its own separate shell, a cd would have no effect for example
pkgs=$(pwd)/pkgs
- set a pkgs variable to $(pwd)/pkgs
- pwd stands for 'print working directory', which outputs the absolute path of the current directory
- we'll need this variable to copy the files back to our repository
cd $(mktemp -d)
- mktemp -d creates a temporary directory and outputs its path
- so we cd into a temporary directory that we created
- we do this, so that we don't have to clean-up the files, the operating system will do that for us at some point
curl -f https://[...]/package-lock.json -o package-lock.json
- get the package-lock.json file from the GitHub repository of Eleventy and save it to package-lock.json file in the current (temporary) directory
prefetch-npm-deps package-lock.json > $pkgs/11ty-eleventy.sha256
- calculate the hash with of the package-lock.json file with prefetch-npm-deps
- and save it (>) to $pkgs/11ty-eleventy.sha256 file in our repository
cat package-lock.json | jq --raw-output ".version" > $pkgs/11ty-eleventy.version
- print out the package-lock.json file (cat) and pass it along (|) to jq which extracts the version ('.version') and saves it (>) to $pkgs/11ty-eleventy.version file in our repository

To get the new dependencies in your development shell, make sure you leave (CTRL+D) and re-enter the development shell (nix develop). Now we can run just update-eleventy. You'll see that two new files appeared in the pkgs folder, a 11ty-eleventy.sha256 and a 11ty-eleventy.version. If you open them, you'll see what you expect to see from the filename, a hash and a version.

Let's use these two new files in our pkgs/11ty-eleventy.nix file. I used a suffix of main for the version, since we're using that branch of the Eleventy repo. A better approach would be to use a tagged release instead.

diff --git a/pkgs/11ty-eleventy.nix b/pkgs/11ty-eleventy.nix
index c6adbfa..240d557 100644
--- a/pkgs/11ty-eleventy.nix
+++ b/pkgs/11ty-eleventy.nix
@@ -3,9 +3,9 @@
 pkgs.buildNpmPackage {
   # Package name
   pname = "eleventy";
-  version = "1.0.0";
+  version = (builtins.readFile ./11ty-eleventy.version) + "main";
   src = src;
-  npmDepsHash = "sha256-LGdCM1gjt3hRn7BiIlbA4e2HOiQ6e/qkAtWp0Qwn+PE=";
+  npmDepsHash = builtins.readFile ./11ty-eleventy.sha256;
   dontNpmBuild = true;
   meta = with pkgs.lib; {
     description = "A simpler static site generator";

And after adding both new files to our git (git add pkgs), we can try and build eleventy again with nix build .#eleventy. Success!

Taking a look at the nix store, we can see it matches the version reported by eleventy.

❯ readlink result
/nix/store/j7kr145ws70in0sbj91yn2ba0m64kmih-eleventy-3.1.2-beta.2-main

❯ result/bin/eleventy --version
3.1.2-beta.2

One thing to note here is that if you only run just update-eleventy and don't run just update (nix flake update alias), the hash will at some point go out of sync, since flake.lock will be frozen in time and so will the src that we're passing into pkgs/11ty-eleventy.nix, but the package-lock.json that we're fetching will not be. You'll get a hash mismatch and you'll have to update the flake.lock file with just update.

So let's fix that and make sure both are run at the same time.

diff --git a/justfile b/justfile
index c7450cb..8de6672 100644
--- a/justfile
+++ b/justfile
@@ -9,11 +9,11 @@ help:

 # Update project dependencies
 [group('General')]
-update:
+update: _update-eleventy
     nix flake update

 # Update packages sha256 and version
-update-eleventy:
+_update-eleventy:
     #!/bin/bash
     pkgs=$(pwd)/pkgs
     cd $(mktemp -d)

So now whenever you run just update, it will also run _update-eleventy, thus they will never be out of sync. I've also made the update-eleventy recipe a private one by prepending _ in front of it.

One last thing before we git commit, let's ignore the result in our .gitignore file (echo "result" > .gitignore).

Commit: Add @11ty/eleventy package to dev shell

Phew! That was quite some work we put in. Now let's build our static site.

Build with Eleventy

Creating an Eleventy generated static site is pretty straightforward, they really do live up to their slogan.

Let's create an index.html file in our repo root.

<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
</head>
<body>
    <h1>Hello, World!</h1>
</body>
</html>

That should do it.

Now let's enter our development shell and run eleventy to build the static site.

(I also gitignored _site at this point echo "_site" >> .gitignore).

❯ eleventy
[11ty] Writing ./_site/index.html from ./index.html (liquid)
[11ty] Wrote 1 file in 0.04 seconds (v3.1.2-beta.2)

Looks good! Let's also try if live development works.

❯ eleventy --serve
[11ty] Writing ./_site/index.html from ./index.html (liquid)
[11ty] Wrote 1 file in 0.05 seconds (v3.1.2-beta.2)
[11ty] Watching…
[11ty] Server at http://localhost:8080/
[11ty] File changed: ./index.html
[11ty] Writing ./_site/index.html from ./index.html (liquid)
[11ty] Wrote 1 file in 0.01 seconds (v3.1.2-beta.2)
[11ty] Watching…

I edited the index.html and the page updated by itself, awesome!

I think we're done here. git commit

Commit: Add index.html

Now let's build the site, with Nix.

Build with Nix

You might be wondering why build with Nix, didn't we just build with Eleventy? Can't I just take the files in _site, copy them to some hosting site and serve them?

Of course. That would be perfectly fine and I won't hold it against you if you want to stop here and do that. Congrats on your new static site!

But if you have NixOS as your server and you're like me and dislike manual work, then continue reading and I will show you how Nix wants you to do this. And I promise it will be easier this time!

Alrighty!

diff --git a/flake.nix b/flake.nix
index dd6cc6d..b31a478 100644
--- a/flake.nix
+++ b/flake.nix
@@ -24,9 +24,24 @@
           inherit pkgs;
           src = inputs.eleventy-src;
         };
+
+        # The static site
+        site = pkgs.stdenv.mkDerivation {
+          pname = "my-static-site";
+          version = "1.0.0";
+          src = ./.;
+          buildInputs = [ eleventy ];
+          buildPhase = "eleventy";
+          installPhase = ''
+            mkdir -p $out/
+            cp -r _site/* $out/
+          '';
+        };
       in
       {
         packages.eleventy = eleventy;
+        packages.site = site;
+        packages.default = site;
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
             just

There is a couple of things going on here.

First, we created a new derivation/package by calling mkDerivation and assigned to a variable called site. In Nix-land almost everything is a derivation, you get used to it.

We set a few things for this derivation:

pname
- package name
- you'll probably set this to the name of your static site
version
- a version number, if anyone uses your package, they might want to know about major version changes, etc
src
- this is what the derivation will consider as its source files, in our case its the current directory (our repo root)
- any changes to the source files (even unrelated to the static site, like .gitignore) will change the derivation
buildInputs
- these are similar to the build inputs that we have for our development environment
- since in our build and install phases we only use eleventy and since mkdir and cp are already part of the stdenv, we only have to specify eleventy here
buildPhase
- Nix builds the package in phases
- in this phase we should produce the built files somehow, in our case that is running the eleventy binary and producing the _site folder
installPhase
- in this phase Nix expects us to create the $out folder and copy the files that we want to be part of the package there
- $out variable resolves to the Nix store path that the package will occupy
- in our case, we want the files in _site to be part of the package, so we copy them

And then we make the package available as an output of our flake. Let's take a look.

❯ nix flake show
[...]
git+file://[...]/create-a-static-blog-with-nix
├───devShells
│   ├───aarch64-darwin
│   │   └───default: development environment 'nix-shell'
[...]
└───packages
    ├───aarch64-darwin
    │   ├───default: package 'my-static-site-1.0.0'
    │   ├───eleventy: package 'eleventy-3.1.2-beta.2-main'
    │   └───site: package 'my-static-site-1.0.0'
[...]

We've made it available under two different names site and default. The default package is a bit special in the sense that you can build it simply with nix build. Let's try it!

❯ nix build
❯ readlink result
/nix/store/25m04s0xmfz2cwlbj1nq7iw9fas9h3jy-my-static-site-1.0.0
❯ cat result/index.html
<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
</head>
[...]

And there you have it! You've built the site with Nix! That wasn't so bad, was it?

Let's git commit and continue on to deploying the site.

Commit: Build the site with nix

Deploy!

Now we can deploy it! Woo!

So what we'll do is:

create a new NixOS configuration that can run as a VM
in the VM, start a Caddy web server
configure Caddy to serve our static site
add a test user to the VM, so we can log in and test that everything works

In this section I will just present the end result, as there are many ways to achieve the same thing and a lot of it will depend on your existing/desired setup.

Before we proceed, we'll need to push the static site repository to a remote. Instructions on how to do this will again vary depending on the forge you're using. I use a self-hosted git forge (Forgejo), so I:

created an empty repository there
git remote add origin git@git.kalu.blue:tech-blog/create-a-static-blog-with-nix.git
git push -u origin main

For convenience I created a sub-directory nixos-configuration in our static site repository to contain the NixOS configuration, but you should create a new repository to contain the configuration for your NixOS server.

Here are the files that I added to that directory:

❯ tree nixos-configuration
nixos-configuration
├── flake.lock
├── flake.nix
├── justfile
└── my-static-site.nix

1 directory, 4 files

Here is the flake.nix. flake.lock will be created for you once you run some nix command (or if you want to mirror my example 100%, you can copy it from the post repository).

I created a separate module file for our static site, just to demonstrate how to pass the flake inputs to modules as an argument (see specialArgs below).

There is also one (inline) module that handles things needed to run this configuration as a VM. Keep in mind the configuration as-is only works on x86_64-linux systems.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    our-site = {
      url = "git+ssh://git@git.kalu.blue/tech-blog/create-a-static-blog-with-nix.git?ref=main&shallow=1";
      inputs.nixpkgs.follows = "nixpkgs"; # Will use the same Nixpkgs as the NixOS system
    };
  };

  outputs =
    { self, nixpkgs, ... }@inputs:
    {
      nixosConfigurations.my-server-name = nixpkgs.lib.nixosSystem {
        specialArgs = {
          # These will be passed as arguments to the modules
          inherit inputs;
        };

        modules = [
          # Essential for test VM
          {
            virtualisation.vmVariant = {
              virtualisation = {
                memorySize = 2048;
                cores = 2;
                # Disable graphics to avoid gtk error
                graphics = false;
              };
            };

            # Create a user, so we can login and test
            users.users.test = {
              isNormalUser = true;
              # Never use this, use `hashedPassword` instead
              initialPassword = nixpkgs.lib.mkForce "123123";
              # So we can use `sudo` mainly for `sudo shutdown now` and to be able to debug `caddy`
              group = "wheel";
            };
          }
          # Some configuration
          {
            nixpkgs.hostPlatform = "x86_64-linux";
            system.stateVersion = "25.11";
          }
          ./my-static-site.nix
        ];
      };
    };
}

Then the module my-static-site.nix.

We have to enable the caddy service and configure one virtual host (example.com) with some configuration that will set it to serve files from our static site package. We also add some gzip compression.

As a bonus, I also included a curl-site shell alias, which you can use in the VM to view our static site main page. I think it also nicely demonstrates how simple it is to use one variable to configure two vastly different systems (web server and shell aliases).

{ inputs, pkgs, ... }:
let
  site-url = "example.com";
in
{
  services.caddy = {
    enable = true;
    # Needs `http://` prefix so that it does not try to request TLS certificates and redirect to 443
    virtualHosts."http://${site-url}".extraConfig = ''
      file_server
      root * ${inputs.our-site.packages."${pkgs.system}".default}
      encode gzip
    '';
  };

  environment.shellAliases = {
    # Test our site
    curl-site = "curl -H \"Host: ${site-url}\" localhost";
  };
}

This configuration will start Caddy and set it serve our static site. It will only be available on localhost, since we have not opened any firewall ports (e.g. 80 and 443). But it was enough for me to start the VM and verify that everything works as intended.

I've also added a just vm recipe (runs nix run ".#nixosConfigurations.my-server-name.config.system.build.vm"). I think its really neat how simple it is to start a full-blown virtual machine with Nix.

Anyway enter the nixos-configuration folder and run just vm. It will build and start the virtual machine and after a while a login screen will be presented. We have configured a user test with a plain-text password 123123. Use that to log in.

Now we can inspect the system:

systemctl status caddy
- we can see its running
- its using config located at /etc/caddy/caddy_config
cat /etc/caddy/caddy_config
- taking a peek at the config file reveals the root path that our web server is serving file from
cat /nix/store/cr5wkgbijfhhp0dy1qm2k30wx8j83bzh-my-static-site-1.0.0/index.html
- yep, this is the index.html that we wrote
curl-site
- yep, this is the index.html file we expected to be served from our web server

❯ cd nixos-configuration
❯ just vm
nix run ".#nixosConfigurations.my-server-name.config.system.build.vm"

[...]
<<< Welcome to NixOS 25.11.20250618.5395fb3 (x86_64) - ttyS0 >>>

Run 'nixos-help' for the NixOS manual.

nixos login: test
Password:

[test@nixos:~]$ systemctl status caddy
● caddy.service - Caddy
     Loaded: loaded (/etc/systemd/system/caddy.service; enabled; preset: ignored)
    Drop-In: /nix/store/bg47546cl8k10w06wg3i002frn2c422f-system-units/caddy.service.d
             └─overrides.conf
     Active: active (running) since Sun 2025-06-22 18:06:27 UTC; 1min 31s ago
 Invocation: 82109b58487c4df48a9d15ba2a958d7e
       Docs: https://caddyserver.com/docs/
   Main PID: 873 (caddy)
         IP: 0B in, 0B out
         IO: 40K read, 8K written
      Tasks: 8 (limit: 2343)
     Memory: 32.6M (peak: 33M)
        CPU: 992ms
     CGroup: /system.slice/caddy.service
             └─873 /nix/store/9820hkh6vc96hjmbqpi9xzfjdrgsw17i-caddy-2.10.0/bin/caddy run --config /etc/caddy/caddy_config --adapter ca>

Jun 22 18:06:25 nixos systemd[1]: Starting Caddy...
Jun 22 18:06:27 nixos caddy[873]: {"level":"info","ts":1750615587.5026293,"msg":"maxprocs: Leaving GOMAXPROCS=2: CPU quota undefined"}
Jun 22 18:06:27 nixos caddy[873]: {"level":"info","ts":1750615587.5131006,"msg":"GOMEMLIMIT is updated","package":"github.com/KimMachin>
Jun 22 18:06:27 nixos caddy[873]: {"level":"info","ts":1750615587.5194187,"msg":"using config from file","file":"/etc/caddy/caddy_confi>
Jun 22 18:06:27 nixos caddy[873]: {"level":"info","ts":1750615587.5768142,"msg":"adapted config to JSON","adapter":"caddyfile"}
Jun 22 18:06:27 nixos caddy[873]: {"level":"info","ts":1750615587.6890154,"msg":"serving initial configuration"}
Jun 22 18:06:27 nixos systemd[1]: Started Caddy.

[test@nixos:~]$ cat /etc/caddy/caddy_config
{
        log {
                level ERROR
        }
}

http://example.com {
        log {
                output file /var/log/caddy/access-http:__example.com.log
        }

        file_server
        root * /nix/store/cr5wkgbijfhhp0dy1qm2k30wx8j83bzh-my-static-site-1.0.0
        encode gzip
}

[test@nixos:~]$ cat /nix/store/cr5wkgbijfhhp0dy1qm2k30wx8j83bzh-my-static-site-1.0.0/index.html
<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
</head>
<body>
    <h1>Hello, World!</h1>
    <p>Eleventy rocks</p>
</body>
</html>

[test@nixos:~]$ curl-site
<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
</head>
<body>
    <h1>Hello, World!</h1>
    <p>Eleventy rocks</p>
</body>
</html>

[test@nixos:~] sudo shutdown now

Everything is working as expected. Hooray!

Commit: Add an example nixos config using this site

Conclusion

We've successfully created a fully reproducible static blog setup using Nix and Eleventy. What started as avoiding a simple Node.js installation turned into a powerful development workflow that demonstrates the strength of Nix's approach to package management and deployment.

While this approach required more upfront investment than a traditional Node.js setup, we now have a system that "just works" across different machines and time. No more "works on my machine" problems, no dependency conflicts, and deployments are as simple as pointing to a git commit.

Next steps

Here are a few things you might want to do next:

As you expand the site, you should move the static site source files to the folder src.
Instead of using the main branch of Eleventy, you should switch to a tagged release. For me, living on the edge feels fine, for you it might not.
You'll probably want to expose the site to the world wide web. That would mean at the very least opening the ports 80 and 443, setting up DNS records to point to the machine and getting a valid TLS certificate (remove the http:// prefix from the module). If you're running the machine at home, you might also need to do some port forwarding.

Hello world!

2025-06-18T00:00:00.000Z

So this is the very first post on this blog. Woo!

I've been thinking about starting a blog for a while now, there just wasn't ever a right time. Anyway, here we are, let's do this!

What I'll write about

I always have a few projects that I'd like to start working on and a few that are in progress.

Right now I'm waiting to get some time to start working on an eInk-display-based image frame and weather dashboard. I've been eyeing the Inky Impression 13.3" one. Still haven't bought it since I also have a Guitar Hero guitar at home that is waiting for me to hook up and play with, and that one already cost me ~100€. So I'm a bit hesitant when it comes to new purchases right now.

I also have a Dell Wyse 5070 Thin Client lying around. I installed Home Assistant on it and even that wasn't as straightforward as I thought it was going to be. Apparently you have to live-boot Ubuntu from a USB stick and then do the installation to the main drive from there. I didn't RTFM well enough on the first run and ended up with it installed to the USB stick. Took a while to figure out why it wasn't booting properly once I took the USB stick out.

Installing Home Assistant was one thing, then I wanted to set up VLAN in my home network. I thought it was going to be a piece of cake and it probably would've been if I had just one router to set up, but I have an OpenWRT set up as a dumb AP connected to an OPNsense router acting as the main router, so I have to set up VLANs on both ends... I've had some luck, but it's not easy to play around and test configuration when my wife watches TV on the same network.

Anyway, what I'm trying to say is that I have a lot of projects going on and I'd like to share them with the world. Maybe you'll learn something by reading about my pain, or maybe, even better, I'll learn something when you write to me about a better way of doing a certain thing.

A few examples of things I'd like to write about at some point:

my homelab, what I host there and how I built it
terminal and shell, not enough people know about CTRL + R for example
Nix/NixOS/Nixpkgs/home-manager tips and tricks
home automation projects, there is always something extra to tinker with
soldering projects, like the air quality sensor I assembled
Emacs and how I configure it
my home network and DNS setup, how to block ads network-wide
how to fix gadgets when they break - like the remote scroll wheel
and so much more...

First post down, hopefully a lot more to follow. Here's to a healthy posting schedule!

Luka builds things

My consultancy stack

Tracking opportunities and getting clients

Calendar

Task management

Time tracking

Invoicing

Development environment

Email and website

Conclusion

Turn your server into a family game streaming hub

VM gaming

Container gaming

Sunshine + Moonlight

How it works under the hood

Security Considerations

Setting it all up

A few tips and tricks

Sharing user folders between multiple clients

Mounting additional folders into the containers

Conclusion

A kid-friendly DIY jukebox

Who is this guide for

What kind of jukebox

What you'll need

The hardware assembly

Installing the OS + PhonieBox software

Uploading your music

Putting it into a nice box

Next steps

Conclusion

Declarative Incus on NixOS with SSO

Prerequisites

My Incus NixOS module

Conclusion

Setting up your own VPN server

The plan

Setting up the VM

Firewall setup

Installing wg-easy

Setup Caddy

Configure WireGuard via wg-easy

Testing the connection

Next steps

Security hardening

Ad blocking

Monitoring and Alerting

Automate the provisioning process

Conclusion

My hardware

The Server

Storage

Root pool

Media pool

PC-Engines APU2 board

Linksys EA7500

NVidia Shield

Raspberry Pi 1

Dell Wyze 5070

The closet

Raspberry Pi 5

My old gaming rig

Caching adventures with Caddy and Nix

How browser caching works

Nix's peculiarities strike again

So what can we do?

Implementation time

Generating ETag files

Configuring Caddy

ETag browser caching process

That's it, we fixed it!

Create a static blog with Nix

Bootstrapping the project

Development shell

Add Eleventy

Build with Eleventy

Build with Nix

Deploy!

Conclusion

Next steps

Configure WireGuard via `wg-easy`