In the first part of this series, we learned how to package a small Go application into a Nix flake. In this second part, we will add a service definition and corresponding NixOS module to it, so that we can easily use it on our machines running NixOS!
For reference, the entire Flake is available here.
To make our service configurable, we will need to add a NixOS module to our flake. These modules allow us to define familiar things such as service.enable. You can read a detailed explanation about them here.
For now we only need to know that it’s just a Nix function returning this set of attributes:
{
options = {
# option declarations
};
config = {
# option definitions
};
}To add such a module to our flake, we need to use the nixosModule attribute of our flake output.
{
outputs =
{ config
, self
, nixpkgs
}:
let
#System types to support.
supportedSystems = [ "x86_64-linux" "x86_64-darwin" "aarch64-linux" "aarch64-darwin" ];
# Helper function to generate an attrset '{ x86_64-linux = f "x86_64-linux"; ... }'.
forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
# Nixpkgs instantiated for supported system types.
nixpkgsFor = forAllSystems (system: nixpkgs.legacyPackages.${system});
version = "0.0.3";
pname = "float";
in
{
nixosModule = forAllSystems (system:
let
pkgs = nixpkgsFor.${system};
in
{ config
, lib
, pkgs
, ...
}: {
# ...
});
};
}Note the use of some helper functions to define the nixosModule for every platform.
Let’s define our first one, a simple option whether this service should be enabled or not:
options.services.float = {
enable = lib.mkEnableOption "enable the float homepage service";
}Here we use the helper function mkEnableOption to create the boolean option. You can read more about all the available option functions here.
Likewise, we can define some more simple options that float specifically will need:
package = mkOption {
type = types.package;
default = self.packages.${system}.float;
description = "float package to use";
};
port = mkOption {
type = types.port;
default = 8051;
description = "port to serve float on";
};
title = mkOption {
type = types.str;
default = "float";
description = "title of the homepage";
};You can find all the types defined here.
Until now, we only used very basic options. However, sometimes we might need to allow users of our module to supply more complex, nested options. A good example of this is the pages we want float to display. It’s a list of links with pretty names for display that we will need to supply as a YAML configuration file. Let’s create a custom “page” option type that represents a single float page.
page = types.submodule {
options = {
name = mkOption {
type = types.str;
description = "name of the page";
};
url = mkOption {
type = types.str;
description = "url of the page";
};
};
};
pageToYMAL = page: {
name = page.name;
url = page.url;
};
configToYAML = input: {
title = input.title;
page_data = map pageToYMAL input.pages;
};Just insert this into a let definition before the body of the module. We can then use the custom type like so:
pages = mkOption {
type = types.listOf page;
default = [ ];
description = "list of sites to be displayed";
};Now with our options defined, we can finally define the config part of our module. This will be applied to the NixOS config of the system using this module. Note that we get the state of the NixOS config before our module is applied, passed as the config parameter to our module function.
We will use that to access the options we created and the user may have chosen to use!
Our goal here is to create a systemd service that will properly configure and start the float package we created in Part 1!
First, let’s create a small helper variable to point to our service options in the config:
cfg = config.services.float;Then we can use the mkIf helper function to only generate our config if the enable option is on:
config = lib.mkIf cfg.enable {
systemd.services.float = {
# ...
};
};Finally, we can populate the body of the systemd service itself!
config = mkIf cfg.enable {
systemd.services.float = {
description = "float home page";
wantedBy = [ "multi-user.target" ];
serviceConfig = {
ExecStart = "${cfg.package}/bin/cmd -port ${toString cfg.port} -file ${
builtins.toFile "config.yml"
(lib.generators.toYAML {} (configToYAML cfg))
}";
ProtectHome = "read-only";
Restart = "on-failure";
Type = "exec";
DynamicUser = true;
};
};
};Note: I’m not that well-versed in systemd services myself, we could probably do more things to harden it.
Pay particular attention to how we referenced the package to locate the float binary and generated a config.yml using our custom functions!
So now you vaguely know how to create a flake that will build a Go application and use it to actually run it inside of your NixOS system. If I made any mistakes in this series, please let me know on mastodon!
Even though Nix has the most and most up-to-date packages, there is always some software you use that is not included yet. You could of course just download a binary, but if you are reading this you probably would like a more declarative way of dealing with the software you use. Thankfully, Nix flakes make it quite easy and quick to package most software. You can even add a NixOS module in the same flake to tell the OS how to configure the service and run it as a systemd service.
The rest of this article assumes that you have a basic understanding of Nix flakes and, for example, already used a flake as a NixOS or home-manager configuration. It’s basically the tutorial I wish I had after setting up my own systems as flakes and needed to run some unpackaged software.
Below we will make a Nix flake for float. It’s a small web service written in golang that you can use to set up a homepage for your homeserver. I chose this as an example because its repo is out of my control, which probably is the case for the software you want to package as well. It’s also configured via a small .yaml file, which is a common case we should cover. Finally, its whole purpose is to run as a service and serve a web page, a good excuse to learn how to do that.
It’s probably a good idea to skim over the float’s readme before continuing - it’ll only take a minute!
For reference later, the code used in this example is residing here.
While we will focus on a go package, almost all of what is written below still applies for rust, node or even haskell packages. See the further reading section below for pointers after you’ve gotten the basics from the float example.
These days, most go programs are quite simple. They consist of a main.go with the entry point of the application and accompanying go.mod and go.sum files defining and locking dependencies (analagous to node’s package.json and package-lock.json). Nixpkgs includes a helper function (pkgs.buildGoModule) that takes all of these and just spits out a compiled app we can use in the rest of Nix. Let’s use it to make a package for float!
{
description = "minimalist Configurable Homelab Start Page";
inputs = {
nixpkgs.url = "nixpkgs/nixos-22.05";
};
outputs = {nixpkgs, ...}: let
# you can also put any architecture you want to support here
# i.e. aarch64-darwin for never M1/2 macbooks
system = "x86_64-linux";
pname = "float";
in {
packages.${system} = let
pkgs = nixpkgs.legacyPackages.${system}; # this gives us access to nixpkgs as we are used to
in {
default = pkgs.buildGoModule {
name = pname;
src = pkgs.fetchFromGitHub {
owner = "aaqaishtyaq";
repo = pname;
rev = "v0.0.3";
sha256 = pkgs.lib.fakeSha256;
};
vendorSha256 = pkgs.lib.fakeSha256;
};
};
};
}Now that’s quite a lot, let’s take it step by step.
{
description = "minimalist Configurable Homelab Start Page";
inputs = {
nixpkgs.url = "nixpkgs/nixos-22.05";
};
...Here we set a small description of our flake, and define our inputs. In this case we only need nixpkgs for some helper functions.
outputs = {nixpkgs, ...}: let
# you can also put any architecture you want to support here
# i.e. aarch64-darwin for never M1/2 macbooks
system = "x86_64-linux";
pname = "float";
in {
...
};
}Here we define our output function that gets passed the inputs as an arg, and set some variables we will refernce later. Note that there are ways to easily make a package for all systems at once, but I left that out to keep it simple. I will leave some further reading material at the end of the post.
Finally, we are getting to the meaty part of actually describing our package!
packages.${system} = let
pkgs = import nixpkgs {inherit system;}; # this gives us access to nixpkgs as we are used to
in {
default = ...;
};Here we set the outputs of our flake, namely the packages attribute set. This name is convention and specifies what packages for what system this flake provides. default is also a convention, it’s the package that will get build when you run just nix build . without specifying anything else.
pkgs.buildGoModule {
name = pname;
src = pkgs.fetchFromGitHub {
owner = "aaqaishtyaq";
repo = pname;
rev = "v0.0.3";
sha256 = pkgs.lib.fakeSha256;
};
vendorSha256 = pkgs.lib.fakeSha256;
};Here we call the pkgs.buildGoModule helper function to actually build float. We have to specify some mandatory arguments: the name of our package, where to get the source from and the sha256 of the packages’ dependencies. We can handily fetch the source directly from GitHub with the pkgs.fetchFromGitHub function.
Now, you might be rightly wondering about all these hashes and the reference to pkgs.lib.fakeSha256. The environment in which Nix evaluates our expressions does not really have access to the internet, except when we provide the hash of what we download before. This makes sure that all our builds are reproducible, and we never have to worry about it resulting in something we didn’t want. More info at the of end of the post!
But where do we get these hashes from? Isn’t that tedious to calculate? Here the fake hashes come to the rescue. Just run nix build .. Now, you will see an error message like:
> nix build .
error: hash mismatch in fixed-output derivation '/nix/store/4kq7wvibcdc10nxcw991cf5yp13y1862-source.drv':
specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
got: sha256-3gMP9VjC8+u41gvzT45LflqZ4uk5+tObBtlJO5SCjwQ=This is nix telling us: Hey, you wanted to download something, but it didn’t match the hash you provided. The helpful part is that it actually gives us the hash it actually downloaded, so we can copy it and substitute it for the sha256 field in fetchFromGitHub. Repeat this step one more time afterwards to get the hash for vendorSha256 as well.
Note: You probably want to verify these hashes match what they should be (i.e. by checking the commit hash on GitHub itself) to make sure nothing funky got introduced somehow.
Now you can run nix build . build one last time and everything succeed. Congrats! You now have the build float binary in ./result/bin/float. Go ahead and try to execute it.
Now that we defined this package, we probably want to use it in our NixOS or home-manager configuration. …
This is covered in part 2 of this series. Click here to get there!
flake-utils repo provides some helper functions to generate package definitions for all systems: https://github.com/numtide/flake-utilsA while ago I got a testing account on rsync.net to try out the experience of using it with zrepl. The experience I has been quite wonderful, and I want to share what I learned with you.
If you use zfs on your NAS, you inevitably think about doing an offsite backup for your data. For this you might use off the shelf tools like Duplicati or borg. As a zfs user you might also be aware of the option to use the zfs send command to send a byte for byte copy of a zfs snapshot to another system running zfs. Writing some shell scripts around this and using it as a backup has numerous drawbacks however.
This is where zrepl comes in, it’s a “one-stop, integrated solution for ZFS replication”. It runs as a daemon on your local nas and your remote system making sure the replication of your datasets proceeds reliably (for example by recovering from network outages) and transparently (by exposing various tools for monitoring).
It it also manages the creation and cleanup of periodic snapshots of your datasets. You could for example keep 24 hourly snapshots on your local nas to quickly recover deleted files while on the other hand keeping 6 monthly snapshots on your remote in case you need to recover something older.
Zrepl is an awesome tool if you want your data to be in two places at the same time while using many native zfs features.
Rsync.net is basically a cloud storage provider without all the fuss. Originally they would just provide you a vm to rsync your files to (hence the name) and make sure they stay there. You can also use various other tools to send them your data like sftp, borg, rclone, git-annex or just good old scp.
The happy coincidence is that their system is based on zfs, just like ours. You even get full access to your own zpool if you sign up for a zfs-send enabled account here. You can simply treat your rsync.net vm as a remote zpool under your control.
As it turns out all this allows us to run zrepl on our remote vm, the rest of this post is about how to set that up. I will skip the setup on your local nas as that is nicely explained by the zrepl docs.
When you sign up for your account you will get a user, password and a host to ssh into. You then want to do basic setup steps like adding a ssh key for your user, but I will skip this part as they have their own guides on how to get started with that. The vms are running on FreeBSD, so some things are a little different. (At least they were for me as a Linux user)
To install zrepl simply run pkg add zrepl.
The next step is making sure that our local NAS’ zrepl daemon can access the rsync.net vm. Zrepl has various transports to make that work. For this guide we will use the simple ssh+stdinserver transport (be aware that this has some throughput limitations however). You should generate a fresh ssh keypair for that on your local machine, putting the private key somewhere your local zrepl daemon can access it. The public counterpart goes into the familiar .ssh/authorized_keys file in addition to some preamble that restrict incoming connections using that key to running zrepl.
command="zrepl stdinserver client1",restrict ssh-ed25519 AAAAC3N...Simply replace the ssh-ed25519 AAAAC3N... here with the public key you generated.
The next step is to configure zrepl by editing the config file at /usr/local/etc/zrepl/zrepl.yml, however we will go into detail on that in the next section.
To enable the zrepl service on your remote simple create the file /etc/rc.conf.d/zrepl and add a line containing zrepl_enable="YES" to it. Then start zrepl by running service zrepl start.
I’ll pride you with a very simple zrepl config for your local nas and remote here. Be sure to read the zrepl docs to tune it for your use case.
Local: /etc/zrepl/zrepl.yml
global:
logging:
- format: human
level: warn
type: syslog
jobs:
- connect:
host: <your rsync.net vm name>.rsync.net
identity_file: <path to the private key you crated>
port: 22
type: ssh+stdinserver
user: root
filesystems:
<datasets you want to replicate>: true
pruning:
keep_receiver:
- grid: 1x1h(keep=all) | 24x1h | 30x1d | 6x30d
regex: ^zrepl_
type: grid
keep_sender:
- type: not_replicated
- count: 10
type: last_n
snapshotting:
interval: 10m
prefix: zrepl_
type: periodic
type: pushRemote: /usr/local/etc/zrepl/zrepl.yml
global:
logging:
- type: "stdout"
level: "error"
format: "human"
- type: "syslog"
level: "info"
format: "logfmt"
jobs:
- name: sink
type: sink
serve:
type: stdinserver
client_identities:
- "client1"
root_fs: "data1"This will make zrepl push snapshots to your rsync.net vm with some snapshotting and pruning. Specifically it takes a snapshot every 10 minutes on your local nas, but only keeps the 10 most recent ones around. Your remote will keep 1 snapshot of each of the last 24h, 1 snapshots for each of the last 30 days and 1 snapshot for each of the last 6 months.
Using zrepl on rsync.net provides us with a fairly straight forward way to replicate our zpool off site, with the added benefit not having to convert our data into other backup formats (such as borg) while keeping most of their benefits. It’s a unique offering that I have not seen anywhere else and hopefully fits your use case as well as it does mine.
Disclaimer: I’m continueing to receive a discounted access to rsync.net.