The tipping point

GitHub used to be the obvious place to put code. It had a reputation that was genuinely earned. Good tooling, a huge community, reliable enough that you didn’t think about it.

That reputation has taken a beating. GitHub has had multiple outages over the last year, the kind that block pushes and CI runs at the worst times. And then there’s the Copilot training on public repositories which I’m not a big fan of.

Neither of those things alone would have moved me. What changed the calculus was Forgejo. It’s a mature, actively maintained Git hosting platform with a straightforward migration path. When the alternative is good enough, the reasons to stay somewhere that’s quietly gotten worse start to feel thin.

So I moved.

What I moved

All my personal repositories, public and private. The goal was to own my own stuff. It was also a useful forcing function to clean out old repos that had been sitting there doing nothing.

Forgejo is running on my NixOS homelab box. It’s LAN-only for now. I’m not exposing it publicly. That’s a deliberate choice. If I want to share something, I’ll figure that out when it comes up.

The GitHub repos are deleted.

How the migration went

Easier than expected. Forgejo has a built-in migration tool that imports a GitHub repo including its history, issues, and pull requests. If you want to keep pushing to GitHub in parallel, it supports setting the old repo as a push mirror.

The only thing that needed reworking was CI. Forgejo Actions uses the same syntax as GitHub Actions, but with one immediate difference: action references need a full https:// URL instead of the shorthand owner/repo@sha format. So actions/checkout@abc123 becomes https://github.com/actions/checkout@abc123. Mechanical, but you have to do it.

That said, I’m using the migration as an opportunity to rethink CI entirely. Rather than stitching together marketplace actions, I’m moving toward a flake-based Nix approach where the pipeline drops into a Nix dev shell and runs commands from there. The goal is that local and CI environments are identical, down to the commit hash of each package. The pre-commit workflow for tf-infra already looks like this:

- uses: https://github.com/DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25
  with:
    extra-conf: "sandbox = false"

- run: nix develop --command pre-commit run

One less thing that only works on GitHub.

Was it worth it?

Yes. Not because anything dramatic changed day-to-day. The repos are still there, git still works the same way. But there’s something satisfying about knowing the authoritative copy of my code sits on hardware I own, in my house, running software I can inspect and modify.

It’s part of the same impulse that got me into self-hosting everything else. I’d rather manage the complexity myself than rent the illusion of simplicity from a platform that can change its terms, train on my data, or simply disappear.

Series: My NixOS Homelab: Part 1 of 10

TL;DR: Traditional Linux servers accumulate changes over time until no one really knows what they’re running. NixOS fixes this by making your entire system configuration a file you can read, commit to git, and roll back at will. The learning curve is steep and the docs aren’t great, but it’s worth it. This series is the story of how I got here.

How I Got Here

My homelab went through a few iterations before landing on NixOS.

First it was the obvious thing: install Ubuntu, apt install everything, configure it by hand. It worked. For a while.

Then I moved to Docker Compose. Services were more portable, easier to version, easier to reproduce. Better, but the host OS was still a snowflake. Every tweak I’d made to the underlying system was stored only in my memory and a pile of shell history.

Then I tried ansible-nas, which at least acknowledged the problem. The idea was right: describe your homelab as code, run a playbook, get a configured system. But it still felt wrong. Ansible describes actions to take, not the state you want. Run the same playbook twice and you’re hoping the idempotency checks hold. The underlying system could still drift between runs.

The moment that crystallised it: a disk died, and I had to rebuild from scratch using ansible-nas. The playbook ran. But it wasn’t a complete picture of what I’d had. Things needed fixing manually. I can’t even remember exactly what. Which is precisely the problem. If you can’t remember what your system needs to be correct, you don’t have a declarative system. You have a script with amnesia.

There had to be a better way.

I Tried NixOS Before. It Didn’t Stick.

I’d actually tried NixOS years earlier, on a laptop. It did not go well.

The learning curve was brutal. The documentation was (and honestly, still is) not great. Nix the language has a unique syntax that nothing prepares you for. And the whole Flakes situation (the feature that makes NixOS properly reproducible) was labelled “experimental”, which at the time made me nervous enough to avoid it. I gave up and went back to something that just worked.

What changed was a HN thread where a bunch of people made the case that NixOS pairs particularly well with LLMs. The argument: because NixOS config is a declarative language with a massive, well-structured package repository, an LLM can actually reason about it (I am aware LLMs don’t actually think but for the sake of the conversation, we’ll go with that word). It can look up available options in nixpkgs, write correct module config, and catch mistakes in ways that are much harder with imperative shell scripts.

I decided to try again, this time leaning into that. The workflow I landed on: plan changes with Claude Opus (for the design thinking), implement with Claude Sonnet (for the actual Nix config), review the diff myself before applying. This is not a post about AI-assisted infrastructure, but it’s worth being honest that the tooling is part of why it finally clicked.

NixOS: Your Entire System Is a File

NixOS takes a radically different approach to the problem. Instead of running commands that mutate system state, you declare what your system should look like in a set of configuration files. Then you apply that configuration, and NixOS makes it so.

The entire state of my server (every installed package, every service, every systemd unit, every user, every open port) is described in a git repository. To understand what my server is running, I read the config. To change something, I edit a file and run nixos-rebuild switch. To undo that change, I run nixos-rebuild switch --rollback and I’m back to exactly where I was before.

It sounds almost too good, so let me be clear: NixOS is not easy. The learning curve is real. The Nix language takes getting used to. The ecosystem has rough edges. There are times you’ll spend an afternoon solving a problem that would’ve taken five minutes on Ubuntu.

But once it clicks, it changes how you think about infrastructure. Going back to imperative config feels like giving up something important.

The Mental Model Shift

Before NixOS makes sense, you need to internalise one idea:

NixOS doesn’t modify your system. It builds a new one and switches to it.

When you run nixos-rebuild switch, Nix evaluates your configuration, builds every package and config file from scratch in an immutable store (/nix/store), and then atomically switches the running system to that new generation. Your previous configuration still exists. It’s still in the boot menu. You can switch back to it instantly.

This has a few profound consequences:

There is no “system state” outside your config. Anything you set up by hand outside of your Nix config doesn’t survive a rebuild. This sounds punishing at first. It’s actually liberating. It forces you to commit changes to config rather than letting them drift into the void.

Every package is content-addressed and isolated. Two packages can depend on different versions of a library, both installed simultaneously, with zero conflict. The infamous “dependency hell” problem is just… gone.

Rollbacks are instantaneous. Because each nixos-rebuild switch produces a new system generation and the old one is kept, rolling back means rebooting and picking the previous entry from GRUB, or running nixos-rebuild switch --rollback without even rebooting.

Reproducibility is built in. With Nix Flakes (which we’ll use from day one in this series), every input to your system (nixpkgs itself, every community module, every tool) is pinned to an exact commit hash. Your flake.lock is a complete bill of materials for your system. Check it into git and you can rebuild the exact same system six months from now on entirely different hardware.

Why Not Just Use Ansible?

Fair question. I tried that (via ansible-nas, specifically).

Ansible brings idempotence and repeatability, but it’s still fundamentally imperative. It describes actions to take, not the desired state of the system. Run the same playbook twice and you’re hoping the authors wrote proper idempotency checks everywhere. The underlying system packages are still managed by the distro’s package manager and can drift between runs. When I had to rebuild after a disk failure, ansible-nas got me close, but not all the way there.

Docker Compose / Podman solves the “which version of this app” problem for containerised workloads, but your host system is still a snowflake. The kernel, system packages, networking configuration, secrets management. All of that lives outside the containers and can drift.

NixOS manages everything: the host OS, the kernel, system services, user packages, dotfiles via Home Manager, and containers too if you want them. The whole stack.

What We’re Building: Meet bunk

Throughout this series, I’ll be working with a real machine: a homelab server called bunk.

Hardware:

• AMD Ryzen CPU
• Gigabyte GA-B450M-S2H motherboard
• 465 GB NVMe OS drive
• 4 × spinning HDDs in two ZFS mirror pools (~6 TB usable)

Services running (all declared in Nix config):

That’s 30+ services, all declared in Nix, all backed up to two separate cloud providers. The system configuration lives in a git repository and rebuilding from scratch is one command.

One honest caveat: the system is declarative, but application-level configuration is not always. Some services can be configured entirely through NixOS module options. Some accept environment variables. Some require you to click through a setup wizard on first run and store their state in a database. I think of it in three tiers: NixOS module options where possible, environment variables for secrets and simple settings, and Click-Ops as a last resort. The Click-Ops stuff is backed up offsite and I can roll back the system around it, so I’m comfortable with that trade-off. I revisit it once a year to see if anything can move up the chain.

Not all services support SSO either. Some won’t let you disable their built-in auth at all, and others lack OIDC support entirely. For those, Authelia sits out and the app handles its own authentication. It’s not perfectly uniform, but it works.

The Core Concepts You’ll Need

Before diving into installation in Part 2, here are the key ideas that will come up repeatedly:

Nix (the language)

A purely functional, lazily-evaluated language used to describe packages and configurations. It has an unusual syntax that takes some getting used to. You don’t need to master it to be productive, but you do need to be comfortable reading it.

# A simple NixOS service declaration
services.caddy = {
  enable = true;
  virtualHosts."jellyfin.maha.nz".extraConfig = ''
    reverse_proxy localhost:8096
  '';
};

Nixpkgs

One of the largest package repositories in existence, with over 100,000 packages. It’s also the source of NixOS module definitions: those services.* and programs.* options that let you configure system services declaratively.

Nix Flakes

An experimental (but widely adopted) feature that pins all your Nix inputs to exact versions, making builds fully reproducible. We’ll use flakes from day one. Think of flake.nix as package.json and flake.lock as package-lock.json, but for your entire operating system.

Home Manager

A Nix-based tool for managing user-level configuration (dotfiles, user packages, shell config). We’ll use it as a NixOS module so user and system config live in the same git repo.

Generations

Each time you run nixos-rebuild switch, NixOS creates a new generation (a snapshot of your system configuration). You can list them with nix-env --list-generations, boot into any of them from the bootloader, and roll back instantly. Old generations are garbage-collected when you run nix-collect-garbage.

The Trade-offs (Let’s Be Honest)

NixOS is not for everyone. Here’s what you’re signing up for:

The Nix language is genuinely weird. It’s not Python or YAML or HCL. It’s a functional language with lazy evaluation, and some concepts (like lib.mkIf, lib.optionalAttrs, overlays) take real effort to understand if you are not that smart like me.

Error messages can be cryptic. When your config fails to evaluate, the error output is sometimes helpful and sometimes looks like it was generated by a Turing machine having an existential crisis.

The ecosystem moves fast. Nixpkgs is massive and well-maintained, but NixOS-specific modules vary in quality. Some services have beautifully-designed modules with every option exposed. Others have bare-bones modules that still require manual workarounds.

First-time setup is slower. Doing what takes ten minutes on Ubuntu might take an hour on NixOS the first time, as you figure out the right module option or why your service won’t start.

The payoff is real. After the initial investment, day-to-day operations become remarkably smooth. Adding a new service is adding a few lines to a config file. Upgrading the whole system is nix flake update && nixos-rebuild switch. Breaking something is a five-second rollback.

What’s Coming in This Series

Here’s the roadmap:

1. Part 1 (this post): Why NixOS?
2. Part 2: Installing NixOS with Flakes and ZFS from day one
3. Part 3: Structuring a config that doesn’t fall apart
4. Part 4: Secrets management with agenix (encrypted config in git)
5. Part 5: Caddy + Authelia: SSO for every service
6. Part 6: Self-hosting a media stack the NixOS way
7. Part 7: Running containers when NixOS modules don’t exist
8. Part 8: Backups with Restic + BorgBackup
9. Part 9: Monitoring, alerting, and knowing when things break
10. Part 10: Deploying, updating, and rolling back without fear

Each article is written to be useful on its own, but they build on each other. If you’re starting from scratch, I’d recommend reading in order. If you’re already running NixOS and just want to know how I’ve handled secrets or backups, jump ahead.

The config repo is private, but all the relevant examples will be in the posts themselves. I’ll include real snippets throughout the series.

Should You Use NixOS?

If any of these sound familiar, NixOS is probably worth your time:

• You’ve ever broken a server and thought “I have no idea how I set this up 2 years ago.” (Maybe that says something about my appetite for documenting my own stuff)
• You’ve ever avoided upgrading a server because you were scared of what might break
• You care about reproducibility and want your infrastructure to be code
• You want to rebuild a machine from scratch in one command and have it come out identical
• You enjoy learning fundamentally different approaches to old problems

If you just want to run a few containers and don’t want to invest in learning a new paradigm, stick with Docker Compose on Ubuntu. That’s a completely valid choice.

A word on the popular alternatives. Kubernetes comes up a lot in homelab circles. I have no interest in running it at home. It’s a single host, I don’t need high availability, and I don’t want to spend a Sunday afternoon debugging a pod networking issue when I just want to watch a movie. Proxmox I’ve used before and it’s genuinely good, but it doesn’t solve the idempotency problem. You still end up with VMs and containers that drift over time. Same goes for TrueNAS and similar. I also prefer staying close to the metal. I’m comfortable with Linux and I’d rather own the whole stack than add an abstraction layer I have to understand on top of it.

But if you’re ready to think about your homelab the way a software engineer thinks about code (versioned, tested, reviewable, rollbackable), NixOS is worth every frustrating moment of the learning curve.

See you in Part 2, where we’ll boot the installer and write our first flake.nix.

Further Reading

• NixOS Manual: the authoritative reference
• nix.dev: excellent learning-oriented guides
• Zero to Nix: a modern introduction to Nix concepts
• Nixpkgs Search: find packages and NixOS options
• awesome-nix: curated list of community resources
• NixOS In Production: The NixOS handbook for professional use

Written in March 2026. NixOS 25.11 (unstable channel at time of writing), Nix 2.24.

In this post, I explore the technology stack powering this blog, detailing the tools and processes used for both authoring content and deploying the site.

Requirements which I have considered that led me to my final choice:

• Simple: I have a full time job and a family. The last thing I want to do is spend time troubleshooting a k8s cluster if my blog is down. I want to take out complexity out of the equation and make sure I have the least amount of tech friction, so I can focus on the content.
• Cheap: Predictable cost, no surprises needed. Static monthly fee is ideal.
• Reproductible: A side-effect of simplicity, if something is not working and I have spent more than 10 minutes troubleshooting it, blow the whole thing away and re-deploy it easily.
• Fast: Minimalistic theme, fast build time, quick deployments. Keep it light (but in dark mode of course).
• Secure: Use HTTPS, ensure HSTS and other security headers can be easily set.
• Governance: I know I could just do this in GitHub Pages, or some S3/Azure Storage static hosting, but I want to have control over the webserver configuration.

With this in mind, I have decided to host the blog on the smallest DigitalOcean (DO) droplet ($4 USD/month), which comes with 512MB of memory and a 10GB disk, in the Sydney region.

Infrastructure

The nameservers for my domain were already hosted in DO, so I have configured the DNS hostname for the site blog.maha.nz to point to the reserved (floating) IP which is attached to the droplet. The DO firewall is allowing inbound ports for SSH and HTTP(S) and blocking everything else.

Normally my pick of server OS would be the latest Ubuntu LTS, but I have been unhappy with Canonical forcing snaps down our throats, so I have decided to go back to good ol’ Debian, which will not let me down.

NGINX is usually my choice of webserver, but I had heard good things about Caddy and was willing to give it a try. Caddy has a very simple configuration (Caddyfile) and will automatically sort out the TLS certificate using LetsEncrypt, nice and simple. For this scenario, Caddy simply serves the /var/www/html folder, where all the Hugo static content is uploaded to.

For the time being, a very basic uptime monitor is configured in DigitalOcean which will automatically email me when the site is down. I plan to expand on this later on and add more checks, both for the OS & the services.

By now, you may be thinking “This sure sounds like a lot of manual configuration”. Let me re-assure you that all of this is deployed via Terraform, then I make use of cloud-init user data to configure the OS and webserver to the point where Caddy serves an empty folder.

The Terraform code looks like this:

• First I create the cloud init configuration, which comes in two stages:

data "cloudinit_config" "blog" {
  gzip          = false
  base64_encode = false

  part {
    filename     = "cloud-config.yaml"
    content_type = "text/cloud-config"

    content = file("${path.module}/cloud-config.yaml")
  }

  part {
    filename     = "setup-caddy.sh"
    content_type = "text/x-shellscript"

    content = file("${path.module}/setup-caddy.sh")
  }
}

In the first stage, the cloud-config.yaml installs some base packages via apt, creates the caddy user which the webserver runs as, adds the pubkey for this user so I can deploy using ssh with key auth. Finally it installs the Caddy webserver.

#cloud-config
package_update: true
package_upgrade: true

packages:
  - curl
  - debian-keyring
  - debian-archive-keyring
  - apt-transport-https
  - gnupg
  - rsync
  - lsof

users:
  - name: caddy
    ssh_authorized_keys:
      - 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICB5N1kyv35KTvDXBrqDs4n1x/mQPxk2eC/h7/htnyOx caddy@blog.maha.nz'

runcmd:
  # Add Caddy official repository
  - curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
  - curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
  # Update package list
  - apt update
  # Install Caddy
  - apt install -y caddy

• In the next stage, the setup-caddy.sh script is executed. This creates the public www folder, sets up the permissions for it and applies the Caddyfile configuration:

#!/bin/sh

PUBLIC=/var/www/html

mkdir -p ${PUBLIC}
chown -R caddy:caddy ${PUBLIC}

cat << EOF > /etc/caddy/Caddyfile
{
  email REDACTED
}

blog.maha.nz {
  root * ${PUBLIC}
  file_server

  # Add multiple headers
  header {
      X-Frame-Options "deny"
      X-XSS-Protection "1; mode=block"
      Content-Security-Policy: "default-src 'none'; manifest-src 'self'; font-src 'self'; img-src 'self'; style-src 'self'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'"
      X-Content-Type-Options: "nosniff"
      Strict-Transport-Security: "max-age=31536000; includeSubDomains; preload"
      Cache-Control: max-age=31536000, public
      Referrer-Policy: no-referrer
      Feature-Policy: microphone 'none'; payment 'none'; geolocation 'none'; midi 'none'; sync-xhr 'none'; camera 'none'; magnetometer 'none'; gyroscope 'none'
  }
}
EOF

systemctl restart caddy

This data block is passed as the user_data attribute when we create the droplet:

resource "digitalocean_droplet" "web" {
  image  = "debian-12-x64"
  name   = "do-web-1"
  region = "syd1"
  size   = "s-1vcpu-512mb-10gb"

  user_data = data.cloudinit_config.blog.rendered
}

Now the webserver is up, and Caddy has configured a TLS certificate, but no content has been uploaded yet to the public folder, it is at this point where we will start getting a 404 status code response for our root https://blog.maha.nz/. Before this, we do not get any HTTP response because the web server is still launching.

The content can be deployed now, and I will cover that process in the Authoring > Deployment section.

Infra Deployment

I use HCP Terraform free tier to deploy all DigitalOcean infrastructure, including my DNS records. For deploying I use a VCS workflow, where a push to my private infra GitHub repo will trigger a Terraform plan & apply.

Authoring

The blog is hosted as a github public repository. The source directory for Hugo is the ./src folder. To add a new post I add it as Markdown to the ./src/content folder. The theme is the Hugo Bear Cub theme which is added as a Git submodule.

Dependencies are installed via the nix flake available at the root of the repository, this can be loaded either manually with nix develop or with a direnv configuration that applies the flake when you enter the root folder.

I edit the md files with my primary editor helix or with Visual Studio Code as my backup editor if that is ever needed.

Content Deployment

Local

My SSH config is configured with the user, host & identity file for the blog. With this in place I can simply run the deploy.sh script locally and it will build the site then rsync it over.

This is simple and fast enough for my needs, I may wrap this up in a Makefile or Taskfile later on.

Github Workflow

A Github action has been setup which will deploy the site contents. This can be trigerred on push, manually, and it will also run on a schedule every 5 minutes. The 5 minutes is a best effort though, as Github can delay your schedule during periods of high loads.

The workflow first checks the status code returned by a curl GET request to the root of the blog. When the response status code is 404 it means that I have redeployed the infra and the droplet has been rebuilt. Because the webserver responds to http traffic, but there is no content at the root, it is implied that the site is ready to have its content re-deployed, so the workflow will execute.

The deployment is a recreation of the rsync deploy script, as GitHub actions. Hugo is pinned to a specific version which should match the version retrieved via the nix flake.

The ECDSA key that allows the rsync command to succeed is read as a GitHub secret, we need to disable StrictHostKey checking and ignore known hosts signature because each droplet rebuild will give us a different host key.

I will consider adding a GitHub self-hosted runner in the future if I want to reduce the time the site is unavailable between rebuilds, but at this point I am ok with this tradeoff.

Analytics

None. I was toying with the idea of using Matomo but I then realised focusing on the numbers would be the wrong incentive for writing. I decided to proceed without any analytics.

Monitoring

For now, I am using a Digitalocean HTTP Uptime Check which will email me when there is no response to a HTTPS request. After I rebuild my home server I will switch it over to use Uptime Kuma

Optimizations

HTTP Observatory is a free online tool that scans websites for security vulnerabilities and best practices, I have used it to help me improve the web security of the site by providing detailed reports and recommendations on various security headers, SSL/TLS configuration, and other critical security measures.

Based on the recommendations, I have managed to achieve an A+ score with the following Caddyfile configuration:

blog.maha.nz {
  root * ${PUBLIC}
  file_server

  # Add multiple headers
  header {
      X-Frame-Options "deny"
      X-XSS-Protection "1; mode=block"
      Content-Security-Policy: "default-src 'none'; manifest-src 'self'; font-src 'self'; img-src 'self'; style-src 'self'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'"
      X-Content-Type-Options: "nosniff"
      Strict-Transport-Security: "max-age=31536000; includeSubDomains; preload"
      Cache-Control: max-age=31536000, public
      Referrer-Policy: no-referrer
      Feature-Policy: microphone 'none'; payment 'none'; geolocation 'none'; midi 'none'; sync-xhr 'none'; camera 'none'; magnetometer 'none'; gyroscope 'none'
  }
}

Future improvements

• Update monitoring to Uptime Kuma
• Wrap up the deploy in a taskfile
• Add self-hosted runner for shorter downtime
• Convert all images to WEBP automatically when Hugo generates the site