In a hurry, or do you prefer seeing the finished result and working your way backwards from there? You can skip to the finished configuration here.

Background

I’ve had my personal site running using the Python web framework Django since 2015. Most of the heavy lifting was done by django-blog-zinnia, a web blog application for Django that provided a lot of tools for authoring and publishing blog articles, such as a WYSIWYG editor and support for comments. I say “provided”, because in the years since, the development of the library languished and eventually stopped, with the last release on PyPI dating to March 10, 2018.

This wasn’t a problem for a long time and went unnoticed until I tried running my site on Python 3.10 on NixOS 22.11, which failed to serve my blog articles at all due to the library lacking support for the newer Python. While it would have been possible to simply deploy this specific Django application under an older Python interpreter (running multiple versions of the same software side-by-side is something NixOS does really well, after all), it did give me a good opportunity/excuse to dive into the world of static site generation, a perfect use case for sites like the one you’re reading right now. Running a dynamic web application on top of a full-featured web framework for what is essentially 99% static content did seem excessive after a while, and at times a small maintenance burden due to the small issues that tended to crop up. After some very brief research, I picked Hugo for no other reason than that it appeared to be the most popular option around.

A week of effort or so later, I had ported almost all of the content from the old Django application to a svelte new Hugo static site. The sole exception was a single POST endpoint that needed to be left around (can you find it?); this was achieved by slimming the Django application down by removing all of the other views and disabling all but the required core middleware and components. Turns out a lot of the included batteries, such as database access, authentication and such could be easily disabled when needed.

Introduction

This article will detail the steps required to serve a Hugo site down from creating the Nix package to actually deploying the site on a running nginx server in a declarative manner, with very little prior experience required with NixOS. That also means being able to add, remove or change bits and pieces of the configuration and being able to deploy the changes without having to worry about the leftover configuration or other state, as is the case with Ansible, Chef and other similar tools.

Manual cleanup and gradually more complicated playbooks become commonplace with such imperative tools over time as the system accumulates cruft: manual edits to configuration files, automatic edits made by package managers over package updates and other changes that often makes deploying on a fresh system a far different experience compared to deploying on a long-lived system. In contrast NixOS aims to deploy the system from a clean slate every time you run “deploy”, going as far as to break several Linux conventions to achieve this (what do you mean there’s no /bin/bash on my freshly installed system?)

I will assume you already have a NixOS system of some sorts up and running, possibly in a virtual machine or other similar environment. If you don’t have one, the official site has an ISO you can run in a VirtualBox or other VM utility of your choice.

We will be using the following directory hierarchy for the different files. Feel free to create a directory for these anywhere you like, such as the home directory.

├── configuration.nix
├── modules
│   └── hugo-site
│       └── default.nix
└── packages
    └── hugo-site
        └── default.nix

Creating a package for the Hugo application

Your Hugo site is hopefully located in a git repository, private or public.

If your git repository is a private one, you will need to have an SSH agent active when deploying, as otherwise the process will either nag for your SSH passphrase constantly or fail to download the repository at all. One solution I’ve found for this is to launch an ephemeral SSH agent that is kept alive for the duration of a single command and killed afterwards. For example, when deploying a new configuration using nixos-rebuild switch, you could instead provide a wrapper for nixos-rebuild in your shell configuration that takes care of setting the SSH agent:

function s-nixos-rebuild() {
    eval $(ssh-agent -s)
    ssh-add ~/.ssh/id_ed25519_deploy
    trap "kill $SSH_AGENT_PID" EXIT

    sudo nixos-rebuild $@

    kill $SSH_AGENT_PID
}

We’ll start by creating the package derivation in packages/hugo-site/default.nix, which describes how to build the Hugo site. You can consider the term “derivation” analogous to “package specification”, which can include terms such as Arch’s PKGBUILD or Fedora’s RPM spec files. Most notably, Nix uses derivations for many additional purposes besides building software, as we’ll see shortly.

{ lib
, stdenv
, pkgs
}:
 
let
  hugoTheme = builtins.fetchTarball {
    name = "hugo-theme-ananke";
    url = "https://github.com/theNewDynamic/gohugo-theme-ananke/archive/a1a99cf12681ad95b006e648a28139e6b9b75f09.tar.gz";
    sha256 = "07y6mr0ybw0cx37lldqi7hqafxghpi623gj8i21w23yg1yhxid8h";
  };
in
stdenv.mkDerivation rec {
  pname = "hugo-site";
  version = "0.1";
 
  src = builtins.fetchGit {
    url = "https://github.com/gohugoio/hugoBasicExample.git";
    ref = "master";
    rev = "00188bc80985f84f6ee85e41f533dd4a19cae169";
  };
 
  nativeBuildInputs = [ pkgs.hugo ];
 
  installPhase = ''
    mkdir -p themes/ananke;
    cp -r ${hugoTheme}/* themes/ananke/;
    hugo -b http://localhost -t ananke -d $out;
  '';
 
  meta = {
    description = "Hugo project for ${pname}";
    homepage = "https://www.test-site.com";
  };
}

Let’s start from the top: the three variables at the top - lib, stdenv and pkgs - are inputs to our derivation; you can think of them as parameters and the remainder as the function body that actually builds the result we want.

Before the actual function body we declare a variable called hugoTheme containing a path to an extracted tarball; this is downloaded from GitHub using a fetcher, convenient Nix functions that download archives from other services, extract them into an unique directory in the Nix store we can use later. Some of them are documented here. In this case, we download a Hugo theme called ananke that we will use to style our site.

As for the actual function body, we’re calling the mkDerivation function from stdenv. It is both useful in itself for creating “basic” packages, as well as used as a building block for different derivation generation functions. For example, other language-specific derivation generation functions such as buildPythonPackage use stdenv.mkDerivation behind the scenes. Our derivation for the Hugo site is simple enough that we can make do with just mkDerivation.

The installPhase contains the actual build commands that will be executed in the build sandbox. We create a themes directory in the build root to contain the ananke theme and then run the actual hugo command to build the site to $out, the result directory, as you can probably surmise.

The other arguments should hopefully be self-evident and clarified by the documentation. However, there are a few properties I’d like to clarify:

• src is the underlying source code for the package we’re building. The notable part here is the builtins.fetchGit function we’re calling. Like fetchTarball before, this is a built-in function in Nix package manager that allows you to fetch and extract an archive from a remote resource, in this case a git repository; it also supports private repositories that require SSH authentication. If you’re retrieving source code from a public repository on a service like GitHub or GitLab, I’d suggest using a fetcher such as fetchFromGitHub instead. In short, if your project resided on GitHub, you might use something like this instead:

  { lib
  , stdenv
  , pkgs
  , fetchFromGitHub
  }:
  
  stdenv.mkDerivation rec {
    # ...
  
    src = fetchFromGitHub {
      owner = "github-user";
      repo = "github-repo";
      rev = "master";  # Use git branch or tag here
  
      # SHA256 hash is required for reproducibility. When you try to build
      # the package the hash will cause a failure. You can then copy the correct
      # hash here and build the package again.
      sha256 = "1111111111111111111111111111111111111111111111111111";
    };
  
    # ...
  }
  

• The rec keyword next to the curly braces allows the description to use self-referencing. A quick example would be the following:

  stdenv.mkDerivation rec {
    pname = "hugo-site";
  
    meta = {
      # 'rec' required so we can reference 'pname'
      description = "Hugo project for ${pname}";
    };
  }
  

  The example here is somewhat contrived and we could do without the rec here. Still, I’ve found it useful to have it “just in case”, as the package definition can be updated to use references and avoid repetition.

Building the Hugo package

You should now have a Nix file in packages/hugo-site/default.nix or similar location. How do we test and build it?

$ nix-build -E "with import <nixpkgs> {}; callPackage ./packages/hugo-site/default.nix {}"
/nix/store/2mssp8ca820ph31h3ikqinwvwm5n1vnx-hugo-site-0.1

That’s quite the mouthful and why is it necessary? Well, in the package definition we just wrote we used a bunch of functions defined in Nixpkgs such as pkgs, stdenv. In fact, the only function that was not defined in Nixpkgs was builtins.fetchGit (assuming you didn’t replace it with fetchFromGitHub or similar fetcher instead). nix-build does not import Nixpkgs by default; instead, we provide a complete Nix expression with the necessary import using the -E parameter and evaluate it (i.e. build it and return the resulting directory).

The command should print the path to the finished package in your local Nix store. Feel free to inspect that it contains the expected files.

Deploying the Hugo site using nginx

Recall that we used the hugo package from pkgs to build the actual Hugo site. How can we make our own package accessible through this parameter, even if our package is not actually part of Nixpkgs?

Overlay is the solution to this problem, as it allows to extend Nixpkgs with our own packages.

This also marks a good place to create the configuration.nix file, which will be the “entry point” to our deployed site. Start with the following template:

{ nixpkgs, ... }:

{
  imports = [
    ./modules/hugo-site/default.nix
  ];

  nixpkgs.overlays = [
    (self: super: rec {
      hugo-site = super.callPackage ./packages/hugo-site {};
    })
  ];
}

And with that we’ve added hugo-site to the list of packages available through pkgs. Of course, we need to write some more configuration that actually uses the package; this will be done in modules/hugo-site/default.nix which we’ve already imported here.

Next up is the module that will encapsulate the configuration to deploy the site on an HTTP server. Create modules/hugo-site/default.nix with the following content:

{ config, pkgs, ... }:

let
  webDomain = "test-site.com";
in
{
  services.nginx = {
    enable = true;

    virtualHosts."${webDomain}" = {
      serverAliases = [ "www.${webDomain}" ];

      locations = {
        "/" = {
          alias = "${pkgs.hugo-site}/";
        };
      };
    };
  };
}

This declares a nginx server that runs the generated the Hugo site on test-site.com (feel free to change the domain accordingly). All the options used here correspond pretty closely to their “vanilla” nginx counterparts. Most importantly, all NixOS configuration options such as the ones here are best searched using the search.nixos.org/options site. If you’re working on NixOS configurations, it’s likely the one resource you’ll be using the most.

If you’ve been following along so far, there should be only a few steps before you can deploy the configuration and see it in action. Edit the main NixOS configuration file at /etc/nixos/configuration.nix (which can also be a symlink if you prefer to have your configuration elsewhere for easier editing!). In it, add the following import:

{ config, pkgs, ... }:

{
  imports = [
    ./hardware-configuration.nix

    "/path/to/hugo-site/configuration.nix"
  ];

  # ...
}

After that just run nixos-rebuild switch and you should end up with a HTTP server serving the Hugo site on port 80.

$ systemctl cat nginx | grep ExecStart
ExecStart=/nix/store/inn7yf1n8fqrj7z5j9hicn284s3sykcq-nginx-1.24.0/bin/nginx -c '/nix/store/09sqpwb6fren12ydv7qkgr2p2prasr34-nginx.conf'

$ nix-shell -p httpie

[nix-shell:~]$ http GET test-site.com
<html>
...
</html>

Parametrizing the web domain

We now have a working Hugo site, but there’s a small issue: I want to deploy it on an actual domain such as https://test-site.com and have the site map and other pages with absolute URLs built with the correct domain. How do we achieve that?

Remember the parameters we have at the start of each Nix file? Let’s update our derivation for the Hugo site to have an optional parameter for the base URL that we can override, which involves two line changes:

{ lib
, stdenv
, pkgs
, baseURL ? "http://localhost"  # Add this
}:

# ...
{
  # ...
  installPhase = ''
    mkdir -p themes/ananke;
    cp -r ${hugoTheme}/* themes/ananke/;
    hugo -b ${baseURL} -t ananke -d $out;  # Change this
  '';
  # ...
}

Changing our nginx configuration is likewise a trivial change; each package provides an override function that we can use to retrieve a version of the package with any of the parameters changed:

{ config, pkgs, ... }:

let
  webDomain = "test-site.com";
in
{
  services.nginx = {
    enable = true;

    virtualHosts."${webDomain}" = {
      serverAliases = [ "www.${webDomain}" ];

      locations = {
        "/" = {
          alias = "${pkgs.hugo-site.override { baseURL = "https://${webDomain}"; }}/";  # Change this
        };
      };
    };
  };
}

$ nix-shell -p 'ffmpeg.override { withX264 = false; }'

[nix-shell:~]$ ffmpeg -version

$ nix-shell -p 'ffmpeg.overrideAttrs (final: prev: { src = fetchgit { url = "https://git.ffmpeg.org/ffmpeg.git"; rev = "n5.1.2"; sha256 = "sha256-4jcfwIE0/DgP7ibwkrSm/aPiHIMFn34JNcXkCMx4ceI="; }; version = "5.1.2"; })'

[nix-shell:~]$ ffmpeg -version
ffmpeg version 5.1.2 Copyright (c) 2000-2022 the FFmpeg developers
built with gcc 12.3.0 (GCC)
...

Wrapping up

By now you should hopefully have a working nginx installation serving a Hugo site. If not (or you’re simply in a hurry), you can look up the Nix files below for what you should have ended up with.

{ nixpkgs, ... }:

{
  imports = [
    ./modules/hugo-site/default.nix
  ];

  nixpkgs.overlays = [
    (self: super: rec {
      hugo-site = super.callPackage ./packages/hugo-site {};
    })
  ];
}

{ config, pkgs, ... }:

let
  webDomain = "test-site.com";
in
{
  services.nginx = {
    enable = true;

    virtualHosts."${webDomain}" = {
      serverAliases = [ "www.${webDomain}" ];

      locations = {
        "/" = {
          alias = "${pkgs.hugo-site.override { baseURL = "https://${webDomain}"; }}/";
        };
      };
    };
  };
}

{ lib
, stdenv
, pkgs
, baseURL ? "http://localhost"
}:

let
  hugoTheme = builtins.fetchTarball {
    name = "hugo-theme-ananke";
    url = "https://github.com/theNewDynamic/gohugo-theme-ananke/archive/a1a99cf12681ad95b006e648a28139e6b9b75f09.tar.gz";
    sha256 = "07y6mr0ybw0cx37lldqi7hqafxghpi623gj8i21w23yg1yhxid8h";
  };
in
stdenv.mkDerivation rec {
  pname = "hugo-site";
  version = "0.1";

  src = builtins.fetchGit {
    url = "https://github.com/gohugoio/hugoBasicExample.git";
    ref = "master";
    rev = "00188bc80985f84f6ee85e41f533dd4a19cae169";
  };

  nativeBuildInputs = [ pkgs.hugo ];

  installPhase = ''
    mkdir -p themes/ananke;
    cp -r ${hugoTheme}/* themes/ananke/;
    hugo -b ${baseURL} -t ananke -d $out;
  '';

  meta = {
    description = "Hugo project for ${pname}";
    homepage = "https://www.test-site.com";
  };
}

{ config, pkgs, ... }:

{
  imports = [
    ./hardware-configuration.nix

    "/path/to/hugo-site/configuration.nix"
  ];

  # ...
}

NixOS contains a lot of other goodies, such as allowing you to enable Let’s Encrypt certificate creation for a nginx virtual host with a few configuration options, simplifying server configuration radically. Still, I hope this has given you a good “vertical slice” of putting together a simple NixOS web server and perhaps some inspiration to dig more into the myriad of tools NixOS gives you, as they make short work of common configuration problems once you get past the (admittedly steep) learning curve.