xesite/nix-flakes-3-2022-03-31.markdown at 451d49ee15ace001f6f8ae5e7874ec73d6f3993e

12 KiB

Raw Blame History

title

date

series

tags

vod

Nix Flakes: Exposing and using NixOS Modules

2022-03-31

nix-flakes

nixos

twitch	youtube
https://www.twitch.tv/videos/1437346416	https://youtu.be/wCZ9SwmgSck

Nix flakes allow you to expose NixOS modules. NixOS modules are templates for system configuration and they are the basis of how you configure NixOS. Today we're going to take our Nix flake from the last article and write a NixOS module for it so that we can deploy it to a server.

If you haven't read the other articles in this series, you probably should. This article builds upon the previous ones.

NixOS modules are the main building block of how NixOS servers are configured. They are like lego blocks that help you build up a server from off the shelf parts. A module describes a desired system state and they build off of eachother in order to end up with a more elaborate result.

You can think about them like Ansible playbooks, but NixOS modules describe the desired end state instead of the steps you need to get to that end state.

NixOS modules are functions that take in the current state of the system and then return things to add to the state of the system. Here is a basic NixOS module that enables nginx:

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

{
  config = {
    services.nginx.enable = true;
  };
}

This function takes in the state of the world and returns additions to the state of the world. This will use the nginx module that ships with NixOS to give you a basic nginx setup that has the upstream default configuration in it.

NixOS has a way to run other instances of NixOS with NixOS containers. We can use them to test our NixOS module as we write it.

This probably won't work on a non-NixOS machine. You will need to install NixOS in order to test this. For an easy way to do this, see nixos-infect, a script you can put into a cloudconfig when spinning up a new server. You can also install NixOS manually in a VM, but for now it may be better to use a cloud server as the path of least resistance. Installing NixOS with a flake will be a part of a future article in this series.

In Nix you can merge two attribute sets using the // operator. This allows you to add two attribute sets into one larger one, such as like this:

nix-repl> { foo = 1; } // { bar = 2; }
{ bar = 2; foo = 1; }

We will use this to add the container configuration to the flake at the end of the flake.nix file. At the end of your flake.nix (just before the final closing }), there should be a line that looks like this:

});

This is what terminates the outputs declaration from all the way at the top. In order to add the container configuration, you should change this to look like this:

      }) // {
      
      };

Then we can add the container configuration to the flake:

}) // {
  nixosConfigurations.container = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux";
    modules = [
      ({pkgs, ...}: {
        # Only allow this to boot as a container
        boot.isContainer = true;
        networking.hostName = "gohello";

        # Allow nginx through the firewall
        networking.firewall.allowedTCPPorts = [ 80 ];

        services.nginx.enable = true;
      })
    ];
  };
};

This will create a container (with the hostname "gohello") that starts nginx and allows traffic to go to nginx on TCP port 80. You can start up the container with the nixos-container command:

$ sudo nixos-container create gohello --flake .#container
host IP is 10.233.1.1, container IP is 10.233.1.2

Then you can start the container with this command:

$ sudo nixos-container start gohello

And then we can try to connect to nginx to see if it's working:

$ curl http://10.233.1.2
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
    body {}
        width: 35em;
        margin: 0 auto;
        font-family: Tahoma, Verdana, Arial, sans-serif;
    }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>
                                                                           
<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>
                                                                           
<p><em>Thank you for using nginx.</em></p>
</body>
</html>

We have nginx!

Now that we have our container to test with, let's write the configuration for the service. At a basic level we need the following things:

A systemd unit for orchestrating the HTTP server process
nginx configuration to reverse proxy to that HTTP server

Above the container definition, add this basic NixOS module template:

nixosModule = { config, lib, pkgs, ... }:
  with lib;
  let cfg = config.xeserv.services.gohello;
  in {
    options.xeserv.services.gohello = {
      enable = mkEnableOption "Enables the gohello HTTP service";
    };

    config = mkIf cfg.enable {
    };
  };

This will create a NixOS module that will only be enabled when the configuration setting xeserv.services.gohello.enable is set to true. Everything else we do here will build on this.

You can and probably do want to change the namespace xeserv here, it is a placeholder that is not likely to conflict with anything else.

Create a basic systemd service with this template:

config = mkIf cfg.enable {
  systemd.services."xeserv.gohello" = {
    wantedBy = [ "multi-user.target" ];

    serviceConfig = let pkg = self.packages.${system}.default;
    in {
      Restart = "on-failure";
      ExecStart = "${pkg}/bin/web-server";
      DynamicUser = "yes";
      RuntimeDirectory = "xeserv.gohello";
      RuntimeDirectoryMode = "0755";
      StateDirectory = "xeserv.gohello";
      StateDirectoryMode = "0700";
      CacheDirectory = "xeserv.gohello";
      CacheDirectoryMode = "0750";
    };
  };
};

NOTE: You will want to be sure to do the following things to your copy of gohello:

We have updated previous articles and the template accordingly.

This will do the following things:

Start the service on boot (multi-user.target fires once the system is "fully booted" and the network is active)
Automatically restarts the service when it crashes
Starts our web-server binary when running the service
Creates a random user for the service
Creates temporary, home and cache directories for the service, makes sure that random user has permission to use them (with the specified directory modes too)
Enables the service automatically

Then you need to add the nginx configuration. We want this application to have its own virtual host, so we will need to add that as a configuration option under the enable option:

domain = mkOption rec {
  type = types.str;
  default = "gohello.local.cetacean.club";
  example = default;
  description = "The domain name for gohello";
};

Pro tip: anything.local.cetacean.club points to 127.0.0.1. You can use this when testing things.

And then we can add the nginx configuration under the systemd service definition:

services.nginx.virtualHosts.${cfg.domain} = {
  locations."/" = { proxyPass = "http://127.0.0.1:3031"; };
};

Your module should look like this:

nixosModule = { config, lib, pkgs, ... }:
  with lib;
  let cfg = config.xeserv.services.gohello;
  in {
    options.xeserv.services.gohello = {
      enable = mkEnableOption "Enables the gohello HTTP service";

      domain = mkOption rec {
        type = types.str;
        default = "gohello.local.cetacean.club";
        example = default;
        description = "The domain name for gohello";
      };
    };

    config = mkIf cfg.enable {
      systemd.services."xeserv.gohello" = {
        wantedBy = [ "multi-user.target" ];

        serviceConfig = let pkg = self.packages.${pkgs.system}.default;
        in {
          Restart = "on-failure";
          ExecStart = "${pkg}/bin/web-server";
          DynamicUser = "yes";
          RuntimeDirectory = "xeserv.gohello";
          RuntimeDirectoryMode = "0755";
          StateDirectory = "xeserv.gohello";
          StateDirectoryMode = "0700";
          CacheDirectory = "xeserv.gohello";
          CacheDirectoryMode = "0750";
        };
      };

      services.nginx.virtualHosts.${cfg.domain} = {
        locations."/" = { proxyPass = "http://127.0.0.1:3031"; };
      };
    };
  };

Then you can add it to the container by importing our new module in its configuration and activating the gohello service:

nixosConfigurations.container = nixpkgs.lib.nixosSystem {
  system = "x86_64-linux";
  modules = [
    self.nixosModule
    ({ pkgs, ... }: {
      # Only allow this to boot as a container
      boot.isContainer = true;

      # Allow nginx through the firewall
      networking.firewall.allowedTCPPorts = [ 80 ];

      services.nginx.enable = true;

      xeserv.services.gohello.enable = true;
    })
  ];
};

Then you can update the container's configuration with this command:

$ sudo nixos-container update gohello --flake .#container
reloading container...

And finally make a request to the gohello service running in that container:

$ curl http://10.233.1.2 -H "Host: gohello.local.cetacean.club"
hello world :)

As an exercise for the reader, try adding a nixos option that correlates to the --bind flag that gohello uses as the TCP address to serve HTTP from. You will want to have the type be types.port.

You can delete this container with sudo nixos-container destroy gohello when you are done with it.

These are the basics on how to use NixOS modules. Everything else you can do with them builds off of these fundamental ideas. Modules are templates that coordinate packages and configuration into your desired system state. Containers can let you test out modules without having to add them to your currently running system. Modules declare options and emit configuration based on those options.

You can also consume NixOS modules from flakes using the input system, however I will go into more details about this at a later date. If you want more examples of NixOS modules, I would suggest checking out my nixos-configs repository. I have nearly everything neatly modularized and configurable. If you see anything in there that is confusing to you, please reach out and ask. I am happy to answer your questions and your feedback will help me write future posts in this series.

I also have my "next generation" flakes-based configuration experiments here if you want to read through those. I have still been porting over things piecemeal, so it is not a complete replica of my existing configuration.

Next time I will cover how to install NixOS to a server and deploy system configurations using deploy-rs. This will allow you to have your workstation build configuration for your servers and push out all the changes from there.

12 KiB Raw Blame History

12 KiB

Raw Blame History