Nix notes

This is a collection of short notes about Nix and NixOS. Almost each note corresponds to a page, to a Git commit, and to a Nix attribute that can be built.

The result is a virtual machine image that actually runs as noteed.com.

How to read these notes

The notes should be read with a copy of this repository. To make each note correspond to a commit, this repository is heavily rebased. When studying a particular note, especially the first ones, it is best to checkout the corresponding commit to see only the relevant files for that note.

In other words, running git log --patch --reverse should be a readable tutorial about Nix and NixOS. Indeed, the following table of content is generated with git log --reverse!

If you have never used Nix before, you may want to start with the Introduction to Nix, although starting directly below should be more fun.

Bleeding edge

Note: building Digital Ocean images is a recent addition to nixpkgs, and uploading a custom image is a recent feature of doctl. Assuming ../nixpkgs is a recent checkout (around 2019-12-13), I'm using a Nix shell like this:

$ NIX_PATH=nixpkgs=../nixpkgs nix-shell -p doctl

Table of content

Start here: building a Digital Ocean image

In this commit, we introduce a short Nix expression to build a virtual machine image that can be run on Digital Ocean. The expression is short because all the machinery to do the heavy lifting is in nixpkgs. More.

Aside: environment variables used for credentials

In this commit, we talk about two files that are in fact non under version-control. They are used to store credentials for two command-line tools: s3cmd and doctl. More.

Deploying the image to Digital Ocean

In this commit, we add two scripts using the s3cmd and doctl tools. They use the credentials introduced in the previous commit: s3cmd uploads to S3 the image built in the commit before, and doctl is used to import the image into Digital Ocean then spin a new virtual machine. More.

Adding a static site to the Nginx configuration

In this commit, we add a simple static site to our image. In the next commit, we'll see how to update an existing virtual machine with this static site, without rebuilding an image or a droplet. More.

Toplevel: updating a running virtual machine

In this commit, we add a new toplevel attribute, and a deploy.sh script. The toplevel corresponds to the content of a virtual machine (before it is packaged as such), and the deploy.sh script syncs an existing NixOS machine so that it matches the new toplevel. More.

Running the configuration inside a local VM

More.

Using cron to run scheduled jobs

In this commit, we add a very simple system crontab demonstrating how to run a simple command every five minutes. More.

A simple Servant-based HTTP backend service

In this commit, we add a simple Haskell application using Servant. It listens on port 8000 and we modify the Nginx configuration to forward requests to it. This also shows how to register the application as a Systemd unit. More.

Packaging our application as a Docker image

Building Docker images is a useful way to start using Nix where Docker is already established. In this commit, we show how to build a Docker image containing the application we have created in the previous commit. More.

Introduction to Nix

In these commits, we add a few examples to learn Nix. More.

Adding automatic Let's encrypt certificate

In this commit, we use the built-in support for Let's encrypt offered in the Nginx module. More.

Details

The configuration.nix file is taken from the nixos-generators project, which makes it easy to build images in various formats, including the one used here.

I use the same Digital Ocean facility for both S3 and the droplets (i.e. ams3).