Posts on The Campground Blog

Beyond YAML: The Case for Nix as the Common Language of DevSecOps

Tue, 20 May 2025 00:00:00 +0000

Beyond YAML: The Case for Nix as the Common Language of DevSecOps

YAML has long been the “glue” of DevOps – from CI/CD pipeline configs to Kubernetes manifests. It earned its place by being simple and human-readable. But today’s DevSecOps reality exposes YAML’s limitations. Modern software delivery demands more than static config files; it requires enforceable security policies, verifiable builds, and guaranteed reproducibility at every step. In this post, we’ll explore why YAML, despite its ubiquity, is no longer sufficient for DevSecOps and why Nix, a purely functional, declarative build language, is emerging as the smarter foundation for secure, auditable software delivery.

DevSecOps Has Outgrown Basic YAML Configs

Traditional DevOps focused on speed and automation, often satisfied by YAML-driven pipelines and scripts. DevSecOps, however, raises the bar by baking security and compliance into the process from the start. In 2025 and beyond, DevSecOps pipelines must achieve goals that go far beyond what vanilla YAML can express:

Policy Enforcement at Build Time: Security checks and compliance rules should trigger during the build, not after deployment. For example, secrets should never enter a build, and dependency licenses or vulnerabilities should be vetted early. This level of shift-left security demands logic and controls in the pipeline that YAML alone can’t dictate.
Full Artifact Traceability: Every artifact (container image, binary, etc.) needs a provenance. Teams should be able to prove exactly which source code, dependencies, and build process produced a given artifact, a response to supply chain threats. Regulators worldwide now demand this proof of integrity, and it’s not optional for critical systems.
Isolated & Reproducible Builds: DevSecOps assumes that a build run today can be reproduced exactly tomorrow or a year from now, byte-for-byte identical outputs from identical inputs. This requires hermetic, isolated build environments where network access and implicit dependencies are controlled. In practice, that means no “works on my machine” surprises and no drifting configurations between dev and CI.
Continuous Auditability: Audit logs and build materials (SBOMs, source archives) should be automatically produced. If a security incident arises, one should rapidly trace what went into the software and rebuild it in a clean room for verification. DevSecOps makes auditability a first-class citizen of the delivery process.

These needs highlight a fundamental truth: simple configuration files aren’t enough. YAML was designed as a data serialization format, not a programming language. As a result, trying to meet DevSecOps requirements with YAML leads to brittle solutions. Let’s examine why.

Why YAML Falls Short in a DevSecOps World

YAML’s popularity in DevOps stems from its simplicity, but that simplicity comes with severe trade-offs when facing security and compliance demands. YAML lacks the expressiveness and rigor needed for today’s software supply chains. It cannot implement dynamic logic or enforce complex policies by itself, it’s just static data. As one developer bluntly put it, “it’s not possible to have the power of Nix/NixOS with a data language like YAML. It has to be a programming language.” In other words, YAML alone can’t model the sophisticated build rules and verifications that DevSecOps requires.

This limitation has led to an ironic phenomenon: we keep trying to bend YAML into a pseudo-programming language, with templating hacks, embedded scripts, and vendor-specific DSLs layered on top. CI/CD systems allow YAML pipelines to call shell scripts and third-party actions, but that just offloads complexity elsewhere. You end up chaining Dockerfiles, shell scripts, Helm chart YAMLs, and glue logic in CI. This is a fragile assembly of parts that’s hard to comprehend and even harder to secure. YAML offers no composability or abstraction: you can’t easily reuse pipeline components or compose configurations without copy-pasting and manual tweaks. This brittleness undermines both consistency and security. A missed step in one script or a subtle difference between environments can introduce vulnerabilities or deployment errors that YAML alone wouldn’t catch.

Most critically, YAML provides no guarantees about correctness or reproducibility. Two developers might follow the same YAML-defined process and get different results if their environments differ or if external dependencies shift. Nothing in a plain YAML file ensures that, say, the same base image or package version is used every time – that assurance has to come from external tooling. In short, YAML can describe what to run, but not how to guarantee it’s done securely and identically each time. For DevSecOps, that’s not good enough.

Nix: A Functional, Declarative Solution for Secure Builds

If YAML is a static checklist, Nix is a blueprint and a engine combined, a way to declare your entire build and deployment process with the power of a full programming language. Nix is often described as a purely functional package manager, but it is better thought of as a build language and ecosystem that brings predictability and rigor to software delivery. Each Nix build is treated like a mathematical function: given the same inputs, it will always produce the same output, with no hidden side effects. This approach lays a foundation of determinism that is a dream for DevSecOps engineers concerned with tamper-proof builds.

What makes Nix so suited as the common language of DevSecOps? Let’s break down its key characteristics:

Purely Functional and Declarative: In Nix, you describe the desired state (packages, configuration, dependencies) rather than writing step-by-step imperative scripts. The Nix expression language is purely functional and even Turing-complete, meaning it can represent any build logic needed. Unlike YAML, you can use functions, conditionals, and abstractions to create reusable, composable build definitions. The result is that even complex pipelines can be expressed in a single coherent framework, without ad-hoc scripting in multiple languages.
Isolated, Reproducible Builds by Design: Nix builds occur in isolated sandboxes with only the declared inputs available. External network access or undeclared dependencies are blocked unless explicitly allowed. This enforces a “nothing up my sleeve” policy. If it wasn’t declared, it doesn’t get into the build. The same Nix build on any machine (developer laptop, CI server, or production) yields identical results because Nix will fetch the exact versions of dependencies specified and build in a controlled environment. This eliminates the “worked on my machine” problem and ensures consistency between local builds and CI.
Complete Traceability and Auditability: Every artifact built with Nix has a traceable lineage. Nix keeps track of all dependencies (down to specific versions and even the tools used to compile those dependencies). This makes generating a Software Bill of Materials (SBOM) straightforward. The build itself knows everything that went into it. Need to audit or comply with regulations? Nix can export the exact source code and dependencies that produced a given binary, providing a verifiable chain of custody for software. Such transparency is near-impossible to achieve with manual YAML pipelines spread across tools.
Expressiveness with Safety: Because Nix is a real language, it allows powerful composition of components (for example, you can build a library and an application together, sharing only the exact dependencies needed). Yet it remains declarative, meaning you describe end states, and Nix ensures the process respects that description. Its strong typing of data types (strings, lists, sets, etc.) and evaluations can catch errors early – you can’t accidentally reference an undefined variable or mis-order steps as easily as in a free-form script. The Nix ecosystem also provides tested functions and modules (for building common languages or frameworks), so you’re not writing everything from scratch. In sum, Nix offers the flexibility of a programming language with guardrails for reproducibility and consistency.

Reproducibility, Traceability, and Policy Enforcement by Default

A fundamental advantage of adopting Nix is how it makes secure practices the default, not an afterthought. Reproducibility comes out-of-the-box. Every Nix build is identified by a cryptographic hash of its inputs. If anything in the inputs changes (source code, a compiler version, a dependency), Nix will treat it as a different build output. If nothing changes, Nix can even reuse previous build results bit-for-bit. This means that whether a developer builds locally or a CI pipeline builds on a fresh machine, Nix will produce the same binaries, configurations, and images. Consistency is guaranteed, dramatically reducing “it works in staging but not in prod” headaches.

Because Nix requires declaring all inputs, it inherently supports policy enforcement and security checks at build time. Want to ensure no disallowed software makes it into the product? You can globally define allowed sources or versions, and Nix won’t import anything outside those whitelists. Builds can be configured to run in fully sandboxed mode (no network, no impurity), so if a step tries to fetch an undeclared URL or access a secret, it will fail! Exactly what you want for a secure supply chain. This shifts security left into the build process, where issues can be caught early. In fact, organizations concerned with compliance can use Nix to prove that a build had no outside interference: it’s either reproducible from known inputs or it doesn’t build at all.

Moreover, traceability is deeply integrated. With a traditional CI pipeline, assembling an SBOM or audit trail is a painstaking process of aggregating data from Dockerfiles, package managers, and manual records. With Nix, the SBOM essentially falls out of the build. For example, one can query the Nix build graph to get a list of every dependency and produce a formatted SBOM (e.g. CycloneDX or SPDX) in one command. Nix can even bundle the source code of every dependency into an archive for future audits or for compliance with regulations that require proving source integrity. This level of detail gives DevSecOps teams and compliance officers high confidence in the artifacts. As a result, auditability is continuous, every build is ready for inspection without extra work.

One Coherent Pipeline Replacing Many Fragile Pieces

Perhaps the most transformative aspect of adopting Nix is the simplification of the delivery toolchain. Many teams today suffer from a patchwork pipeline: a Dockerfile to build an image, bash scripts to glue steps together, YAML files to configure CI tasks, Helm charts to deploy, and so on. Each piece is written in a different syntax, with different assumptions, often maintained by different people. It’s no wonder things break. The more moving parts and translation layers, the more chances for error.

Nix enables you to consolidate these steps into one coherent, verifiable process. You can replace Dockerfiles with Nix-based container image builds (using Nix functions to produce Docker/OCI images). Instead of imperative shell scripts that install software and set up environments (which can drift over time), you write declarative Nix expressions for those environments. The difference is stark: a Dockerfile might pull in a moving target like “ubuntu:latest” and run arbitrary commands that update packages ( introducing variability), whereas a Nix build will fetch an exact base image or filesystem layer and exact versions of packages, ensuring the build is deterministic. Where a shell script might rely on whatever version of a tool is in the PATH, a Nix script will call a specific, hashed version of that tool from the Nix store. Everything is explicit and locked down!

By eliminating the ad-hoc glue, Nix cuts complexity and risk. There’s no need for a separate config language for tests, another for packaging, and another for deployment. All can be described in Nix or orchestrated by Nix-built tools. This also has productivity benefits: developers and operators speak a common language (Nix) and have a single source of truth for how software is built and run. No more hunting through CI YAML files to figure out what environment variable might be missing, or why a build works in one pipeline stage but fails in another. With Nix, if it builds on your machine, it will build in CI, period. And once built, that same output can be deployed knowing it hasn’t been tweaked or re-packaged by an opaque CI step. The entire flow from source to production can be verified end-to-end.

The bottom line is a drastic reduction in the “unknown unknowns” that plague multi-tool pipelines. Nix’s unified approach replaces the brittle chain of tools (Docker, apt, pip, make, bash, CI config) with a single, reproducible definition. This coherence means fewer surprises and a tighter alignment between development intentions and production reality. For organizations, it translates to fewer failed deploys, faster recovery from issues (because rebuilds are reliable), and easier onboarding of new team members (since there’s one system to learn rather than five).

Conclusion: Lead the Next Evolution – Adopt Nix for DevSecOps

DevSecOps is about making secure and compliant software delivery as fast and automatic as traditional DevOps. But as we’ve argued, trying to achieve that with yesterday’s tools (like plain YAML and a mishmash of scripts) is like trying to secure a modern skyscraper with the blueprint of a wooden shed, it doesn’t meet the moment. Nix offers a path forward. By using a declarative, reproducible, and expressive approach, Nix fulfills the core needs of DevSecOps in a way YAML never can. It enables policy enforcement, traceability, isolation, and auditability from the ground up, not as bolted-on afterthoughts.

Nix isn’t just about security, it’s about business resilience and efficiency. “What once took months to achieve in terms of reproducibility and version control can now be accomplished in a matter of hours.” Organizations adopting Nix have found they can meet stringent security requirements without slowing down development or inflating costs. Developers get to work with the latest tools and libraries, while the Nix framework guarantees that the resulting products are consistent and verifiably secure. Compliance audits that used to take weeks of chasing documentation can turn into an automated report from a Nix build. And when regulators or customers ask for evidence of your software’s integrity, Nix provides an answer grounded in math and computer science, a verifiable “proof” of how your software was constructed.

The momentum behind Nix is growing, with a vibrant community and increasing adoption in industry (its popularity has been growing exponentially in recent years). Forward-thinking leaders are already investing in Nix skills and pilot projects. As an industry, if we embrace Nix as the standard language of DevSecOps, we move toward a future where secure, verifiable builds are the default rather than the exception. Imagine a world where every build output can be trusted, where supply chain attacks are thwarted by design, and where development speed doesn’t suffer for security. That’s the future Nix is pointing us to.

Call to action: It’s time to move beyond the comfort of YAML and scripts and into a more robust paradigm. If you are in a position of leadership encourage your teams to evaluate Nix for your build pipelines and deployments. Start with a small project, leverage the wealth of Nix resources and community support, and see the benefits firsthand. Adopting Nix today is an investment in the stability and security of your software supply chain tomorrow. In an era of ever-increasing cyber threats and compliance pressures, Nix isn’t just a niche tool, it’s a strategic advantage. Embrace the change, and lead your organization into a more secure, reproducible, and confident DevSecOps era.

Nix in the Wild: Taming Terraform with Nix

Sat, 18 Jan 2025 00:00:00 +0000

Welcome back to Nix in the Wild, a series exploring real-world applications of Nix within organizations, using the fictional company Initech as a narrative framework. In this installment, I will explore the integration of Terraform into the Initech Snowfall-lib-based flake, offering a comprehensive guide to adopting this approach in your own workflows. By integrating the Terranix library with custom functions, I have established a foundation for a unified software and infrastructure framework. This framework enables organizations to seamlessly develop, test, and deploy both applications and the infrastructure they depend on.

Before we dive in, a quick disclaimer: I’m relatively new to Terraform, so take my thoughts on it with a grain of salt. I’ve mostly avoided cloud-related tools in the past because of the potential for high costs and the simplicity of working in my home lab. That said, I recognize the importance of having cloud skills in any business or large organization.

I’ll start with a quick intro to the NixOS module system for anyone who’s not familiar with it. From there, I’ll show how I integrated Terranix into the Snowfall structure for organizing flakes. By defining resources like Lambda functions or EC2 images directly in Nix configurations, we can tie these definitions into Terraform workflows, making it easier to connect declarative configuration with practical cloud resource management.

Using Nix with Terraform introduces an opportunity to simplify cloud infrastructure management while improving reusability and consistency. By leveraging modular configurations and Nix’s declarative paradigm, you can create workflows that are both maintainable and scalable. Throughout this post, I will demonstrate how these tools can work together effectively to streamline your approach to infrastructure as code.

Code for this post can be found here

What is Terranix?

My discovery of Terranix began when I started a new project requiring deeper engagement with cloud infrastructure. Up to that point, my experience with Terraform was limited to minor adjustments in existing projects, where I often felt annoyed by its repetitive and fragmented nature. Even in what I’d consider a well-organized Terraform project—complete with proper modules—making a seemingly simple change often required navigating through multiple layers, declaring variables in several places, and painstakingly ensuring consistency. Additionally, running Terraform required working within the correct directory structure, adding yet another layer of friction.

When it came to starting a new project, the lack of straightforward mechanisms to reuse modules across projects without resorting to copy-pasting was frustrating. It’s entirely possible that my limited experience contributed to these frustrations, but the rigidity and verbosity of Terraform always left me searching for a better approach. Determined to find a solution that addressed these pain points, I began investigating alternatives.

Of course, my fondness for Nix naturally influenced my search, leading me to discover Terranix. Initially, I was skeptical, questioning whether this was merely an exercise in rewriting Terraform within Nix for its own sake, or whether there was genuine value to be gained. While I’m an advocate for Nix, I also prioritize practicality—the solutions I build must remain accessible to others who may not share my enthusiasm for Nix.

After exploring examples on GitHub and finding limited resources, my skepticism remained. Nonetheless, I decided to dedicate a weekend to experimenting with Terranix and exploring its potential to streamline my workflow. What I discovered not only addressed my initial concerns but also opened new possibilities for simplifying and enhancing Terraform projects. Let’s dive into what makes Terranix such a compelling tool.

Addressing Terraform’s Verbosity

One of the most immediate benefits of Terranix is its ability to reduce Terraform’s verbosity. Instead of defining variables in multiple places within Terraform, you can leverage Nix variables directly. Additionally, Terranix allows you to utilize Nix functions and modules to further streamline and simplify Terraform configurations, making them more concise and easier to manage.

Enhancing Reusability

Terranix simplifies the creation of reusable modules by allowing you to define and share them within your Nix configuration. This approach promotes modularity and eliminates the need to duplicate code across projects.

How to Use Terranix

Reading through the Terranix documentation helped me get up to speed with writing basic, non-module configurations quickly. However, I found myself questioning whether this approach truly offered an improvement over standard Terraform workflows. While the documentation emphasized modules as a key feature, the process for effectively utilizing them wasn’t immediately clear. In this section, I will clarify how to work with modules in Terranix, explaining it in simpler terms based on my own experiences.

Update `flake.nix`

The first thing we need to do is add "github:terranix/terranix" to the inputs section of our flake.nix

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
  unstable.url = "github:nixos/nixpkgs?ref=nixos-unstable";

  snowfall-lib = {
    url = "github:snowfallorg/lib";
    inputs.nixpkgs.follows = "nixpkgs";
  };

  devshell.url = "github:numtide/devshell";

  nix-tutor.url = "gitlab:usmcamp0811/nix-tutor";

  poetry2nix.url = "github:nix-community/poetry2nix";

  terranix.url = "github:terranix/terranix"; # <-- We added this right here
};

Create a Terraform Configuration

The way that we use Terranix is as just another Nix “package”. This means that we create a new folder in the ./packages directory. I am going to call this cloud-infrastructure you can call it whatever makes the most sense to you. In this folder we add our standard default.nix file and at least one additional Nix file, in this case I am calling it terranix.nix.

├──  packages
│   ├──  cloud-infrastructure
│   │   ├──  default.nix
│   │   └──  terranix.nix

Here’s what you’ll need to include in your default.nix and terranix.nix files. I’ll start with these and then work backward to explain the reasoning behind each step.

default.nix

{ lib, pkgs, system, ... }:
with lib.initech;
mkTerranixDerivation {
  inherit pkgs system;
  modules = [ ./terranix.nix ];
}

This is a helper function I created to wrap the terranixConfiguration function from Terranix. It adds a few extras, like passthru support for creating an S3 bucket to manage Terraform state and handling Terraform apply and destroy actions. The terranixConfiguration function itself only converts Nix configurations into Terraform JSON, so this wrapper streamlines the process. The key argument it takes is a list of Nix files containing the Terranix configurations.

terranix.nix

{ config, pkgs, ... }: {
  config = {
    data.http.public_ip = { url = "http://checkip.amazonaws.com/"; };
    provider.aws.region = "us-east-1";
    backend.s3 = {
      bucket = "initech-state-bucket";
      key = "state/terraform.tfstate";
      region = "us-east-1";
    };
    aws = {
      storage = {
        s3 = {
          enable = true;
          buckets = { initech-tps-reports-bucket = { enable = true; }; };
        };
      };
      lambda = {
        pdf-ocr = {
          enable = true;
          variables = {
            INPUT_BUCKET = "initech-tps-reports-bucket";
            OUTPUT_BUCKET = "initech-output-bucket";
          };
        };
      };
    };
  };
}

This file is more complex than our default.nix, but it’s manageable when broken down. You’re not limited to just one terranix.nix file—you can create multiple files and name them however you like. The content of this file combines two elements: Terraform converted into Nix syntax and calls to the custom Terranix modules I’ve created. I will cover modules in a little bit but take a second and see if you can discern whats happening.

Here’s how Terranix and Terraform compare when defining configurations. The following Nix snippet shows how Terranix expresses these configurations:

data.http.public_ip = { url = "http://checkip.amazonaws.com/"; };
provider.aws.region = "us-east-1";
backend.s3 = {
  bucket = "initech-state-bucket";
  key = "state/terraform.tfstate";
  region = "us-east-1";
};

If you’re familiar with Terraform, the equivalent HCL might look like this:

data "http" "public_ip" {
  url = "http://checkip.amazonaws.com/"
}

provider "aws" {
  region = "us-east-1"
}

terraform {
  backend "s3" {
    bucket = "initech-state-bucket"
    key    = "state/terraform.tfstate"
    region = "us-east-1"
  }
}

The similarity between the two makes Terranix approachable, even for those who aren’t yet familiar with Nix. This allows teams with Terraform experience to get started with Terranix more easily while benefiting from its integration into the Nix ecosystems.

The other part of the terranix.nix file above is the declaration and configuration of Terranix modules for creating S3 buckets and a Lambda function. I’ll dive deeper into Nix modules and how I create them in the following sections. For now, take a moment to review how we’re calling these modules:

aws = {
  storage = {
    s3 = {
      enable = true;
      defaultIpWhiteList = [ ];
      buckets = { initech-tps-reports-bucket = { enable = true; }; };
    };
  };
  lambda = {
    pdf-ocr = {
      enable = true;
      variables = {
        INPUT_BUCKET = "initech-tps-reports-bucket";
        OUTPUT_BUCKET = "initech-output-bucket";
      };
    };
  };
};

This structure showcases how Terranix simplifies and organizes the configuration of cloud resources, keeping everything declarative and easy to manage.

Finally, I want to clarify that this setup represents just a single Terraform configuration. If our requirements call for multiple configurations, we can easily add them within the same repo. All we need to do is replicate the cloud-infrastructure folder under a different name. From Nix’s perspective, each of these is simply a Nix package, making it straightforward to manage multiple configurations.

Deploying our Cloud Infrastructure with Terranix

Now that we’ve walked through how to define your infrastructure using Terranix, let’s discuss how to deploy it. The process involves leveraging passthru attributes provided by the mkTerranixDerivation function to interact with your Terraform configuration.

# Display the Terraform JSON configuration
nix run .#cloud-infrastructure

# Equivalent to `tf apply`
nix run .#cloud-infrastructure.apply

# Equivalent to `tf destroy`
nix run .#cloud-infrastructure.destroy

If you need to manage your Terraform state in an S3 bucket, you can use the create-state-bucket passthru. This passthru simplifies the creation of a bucket to store the state, but you must explicitly reference the bucket in your Terranix configuration—Terranix does not automatically link it to your Terraform setup.

With this setup, it should be relatively straightforward for non-Nix and non-Terraform users to contribute to the Nix ecosystem you’re building in your organization. Developers with strong Terraform skills could create modules that less experienced Terraform users can easily deploy. And this is just the beginning—I haven’t even touched on how custom Nix packages can seamlessly integrate with the resources we deploy using Terraform. That’s coming up, but first, let’s dive into the Nix module system.

Building and Organizing Modules

In this blog series, I haven’t yet covered NixOS modules in the Snowfall library, but that’s coming up now—or at least the concepts of modules as they relate to Terranix. NixOS and Home Manager modules will be covered in a later post.

In the Snowfall structure, NixOS and Home Manager modules are stored in the ./modules directory, so it felt natural to use the same directory for Terraform modules. Since Terraform supports multiple providers, I’ve adopted a structure like ./modules/<provider>/... to keep things organized and scalable for multi-cloud environments. For this post, I’ll focus on building a couple of AWS modules to demonstrate the approach.

A Brief Explanation of the NixOS Module System

The NixOS module system is relatively straightforward once you understand one key concept about the Nix language: attribute sets can be merged together to create a superset. This means that if you have multiple files, each defining an attribute set (e.g., config), and you import them all into your flake.nix, Nix will automatically merge them into a single, combined set. Let’s break it down with an example:

File A defines the following attribute set:

{
  config = {
    a = "something";
    w = {
      something = "in file A";
    };
  };
}

File B defines a different attribute set but also includes some overlapping structure:

{
  config = {
    s = "more stuff";
    w.somethingelse = "in file B";
  };
}

When both files are imported into your flake.nix or another Nix module, Nix will merge them into a single config attribute set. The result would look like this:

{
  config = {
    a = "something";
    s = "more stuff";
    w = {
      something = "in file A";
      somethingelse = "in file B";
    };
  };
}

Notice how the values are combined—Nix doesn’t overwrite existing values unless explicitly told to. Instead, it intelligently merges the structure, appending new attributes wherever necessary.

This merging behavior is the foundation of the NixOS module system that Terranix leverages. It allows you to split configuration across multiple files, keeping things modular and organized. For example, you could have separate files for system services, user configurations, and application-specific settings, and Nix will seamlessly combine them.

Now that you understand how the module system works, let’s see how we can apply a similar approach to Terraform modules.

Creating a Basic Terraform Module

A Terraform module in Nix is essentially a default.nix file that defines the configuration for a specific resource or group of resources. Here’s an example of a basic Terraform module for creating S3 buckets:

default.nix

{ config, pkgs, ... }: {
  provider.aws = {
    region = "us-east-1";
  };

  resource.aws_s3_bucket.example = {
    bucket = "example-bucket";
    acl = "private";

    tags = {
      Name = "example-bucket";
      Environment = "production";
    };
  };
}

This file defines a module for configuring S3 buckets, specifying attributes like the region, bucket name, and tags. When imported into a larger configuration, this module integrates seamlessly with others, leveraging Nix’s merging mechanism to ensure consistency and flexibility.

By structuring Terraform modules like this, you can easily reuse and combine them to create more complex infrastructure configurations while keeping everything clean and maintainable. To include these modules in your cloud-infrastructure package discussed earlier, simply add them to the modules list.

While this approach is effective, there’s room for improvement. In the next section, I’ll show how we can refine and enhance this process.

Using Options to Customize Modules

One drawback of the simple module above is that it doesn’t allow customization—every time we use it, the bucket name would always be example-bucket. Wouldn’t it be great if we could parameterize the name? Well, we can!

One of the most powerful features of the NixOS module system is the ability to define options. Options provide a consistent interface for configuring modules, allowing users to customize behavior without modifying the module’s internals. This flexibility makes modules reusable and adaptable to different use cases.

Let’s dive into how options work and how you can use them to make your Terraform modules more customizable and user-friendly.

How do I create Options?

Options are configuration parameters enriched with metadata that define how a module behaves. They specify:

Name: The key used to set the value in your configuration.
Type: The expected data type (e.g., string, boolean, list).
Default Value: A fallback value applied if none is explicitly provided.
Description: A brief explanation of the option’s purpose.

By defining options, you provide a clear and consistent interface for users, making modules easier to configure and integrate into projects.

Note: You can set the default value of an option to depend on other parts of your configuration. This allows modules to work seamlessly together by default while still enabling customization for scenarios that require deviations from the standard setup. Additionally, modules can enable dependent modules automatically, ensuring that all necessary dependencies are configured without manual intervention.

Defining Options in a Terraform Module

Here’s an example of how to define options in a Terraform module for managing S3 buckets:

default.nix

{ config, lib, ... }: with lib;

{
  options.aws.storage.s3 = {
    enable = mkOption {
      type = types.bool;
      default = false;
      description = "Enable or disable S3 bucket creation.";
    };

    region = mkOption {
      type = types.str;
      default = "us-east-1";
      description = "The AWS region for the S3 buckets.";
    };

    buckets = mkOption {
      type = types.listOf types.str;
      default = [];
      description = "List of S3 bucket names to create.";
    };

    tags = mkOption {
      type = types.attrsOf types.str;
      default = {};
      description = "Tags to apply to all S3 buckets.";
    };
  };
}

This example defines several options:

enable: A boolean to toggle bucket creation.
region: A string specifying the AWS region.
buckets: A list of bucket names.
tags: A set of key-value pairs for tagging the buckets.

Using Options to Customize Modules

To use the option, we can refer back to our example above, where we defined an S3 bucket and a Lambda job. It’s important to note that the option path options.aws.storage.s3 maps to the module aws.storage.s3. While this mapping has no hard relationship to the file’s physical location, maintaining a folder structure consistent with the module path is helpful for organization and clarity.

This configuration allows us to customize the module by:

Enabling S3 bucket creation.
Creating an S3 bucket named initech-tps-reports-bucket.
Defining Lambda functions with environment variables linked to the S3 buckets.

Note: If you examine the ./modules/terraform/aws/lambda/pdf-ocr module, you’ll notice that the initech-output-bucket is automatically created because the s3 module is invoked within the pdf-ocr module. This modular design keeps related configurations interconnected and manageable.

Integration with the Nix Ecosystem

Using Nix to generate Terraform configurations makes it easy to integrate components already packaged with Nix. A great example of this is the Lambda job from our example above.

The Lambda job uses a Python script run from within a container, which is packaged and built by Nix. This integration combines custom Nix functions with Terraform’s null_resource module, allowing Terraform to execute arbitrary shell scripts during deployment. This tight coupling enables seamless integration between Nix and Terraform.

How the Integration Works:

Build the Container Image: Nix builds the Lambda container image as a tar file.
Push to AWS Registry: A custom script pushes the container to a registry accessible by AWS, set up via Terraform.

Here’s an example Nix configuration for the null_resource module:

resource.null_resource = {
  provisioner = {
    local-exec = {
      # ****************************************************************** #
      # This generates the shell script to push the image to the registry. #
      # ****************************************************************** #
      command = "${build-push-lambda-image cfg.job}/bin/build-push ${
        config.resource.aws_ecr_repository."${cfg.job.registry-name}" "repository_url"
      }";
      # ****************************************************************** #
    };
  };
  depends_on = [ "aws_ecr_repository.${cfg.job.registry-name}" ];
  triggers = {
    always_run = true;
    registry_url =
      config.resource.aws_ecr_repository."${cfg.job.registry-name}" "repository_url";
    # ****************************************************************** #
    # This ensures the image is pushed only when its hash changes.        #
    # ****************************************************************** #
    package_hash = lambdaImageTag cfg.job;
  };
};

Key Points:

Shell Script Generation: The build-push-lambda-image function generates a script that pushes the container to a registry. The repository_url is dynamically retrieved from the aws_ecr_repository attribute defined in Terraform.
Efficient Updates: Using package_hash, the container is only pushed when its content changes, ensuring efficiency and avoiding unnecessary redeployments.
Tightly Integrated Workflow: Nix builds the container image and Terraform deploys it in a single, unified workflow.

This approach streamlines cloud infrastructure deployment. No longer do you need separate steps to build a container and then deploy it with Terraform—everything is integrated, leading to greater efficiency.

But it doesn’t stop with Lambda jobs. The same logic can apply to:

EC2 Deployments: Create an AMI using Nix flakes, deploy it to AWS, and launch EC2 instances.
Long-Running EC2 Instances: Deploy a NixOS configuration directly to EC2 instances to manage them beyond their base image.

With Nix, you can manage your entire cloud infrastructure and application stack from a single configuration, making integration testing, deployment, and maintenance more efficient and easier to manage.

In future posts, I’ll show how this pattern can be extended to EC2 instances. For now, that’s beyond the scope of this post, but the possibilities with Nix and Terraform are nearly limitless.

Understanding Terranix’s Nuances

For the most part, translating Terraform configurations into Terranix expressions is straightforward. However, accessing attributes from Terraform resources or data sources within Terranix can initially seem unclear.

This issue has been discussed in an open issue on the Terranix GitHub repository and in a related pull request. While the process is relatively simple, it is not well-documented, which can cause confusion for new users.

To access an attribute, you call it as a function. For example:

`1`	`config.data.aws_iam_policy_document.assume_role "json";`

In this example, the json attribute is retrieved from the aws_iam_policy_document.assume_role data source. This syntax makes it easy to extract specific details from a resource, but understanding this pattern is essential to using Terranix effectively.

Important Note:

One key discovery is that fetching an attribute like the example above must be done in the module scope, not at the library function level. For instance, you cannot create a library function containing something like:

`1`	`config.data.aws_iam_policy_document.assume_role "json";`

This will fail when called elsewhere. This limitation is why the functions I use in the null_resource are structured as they are, rather than being abstracted into simple wrapper functions. While this may seem less tidy, it ensures compatibility with how Terranix handles configurations and attributes.

Breaking Down My Terranix Library Functions

This section provides an overview of the custom library functions I created for integrating Terranix with a Snowfall-based flake. These functions help streamline the process of discovering and using Terraform modules, generating configurations, and deploying infrastructure.

`findDefaultNixFiles`

This function scans a directory recursively to find all default.nix files, making it easier to organize and discover Terraform/Terranix modules. It’s particularly useful for managing modules under a ./modules/terraform structure.

findDefaultNixFiles = path:
  let
    scanDir = dir:
      let
        entries = builtins.readDir dir;
        files = builtins.filter
          (name:
            let entry = entries.${name};
            in entry == "regular" && builtins.match ".*default\\.nix$" name != null)
          (builtins.attrNames entries);
        filePaths = builtins.map (file: "${dir}/${file}") files;
        subDirs = builtins.filter
          (name: let entry = entries.${name}; in entry == "directory")
          (builtins.attrNames entries);
        subDirPaths = builtins.concatLists
          (builtins.map (subDir: scanDir "${dir}/${subDir}") subDirs);
      in
      filePaths ++ subDirPaths;
  in
  scanDir path;

This function currently exports the list of file paths, which can be imported into other flakes. While I’d like to make the modules indexable like nixosConfigurations, this functionality remains a work in progress.

Example usage in the flake output:

outputs = inputs:
  let
    lib = inputs.snowfall-lib.mkLib {
      inherit inputs;
      src = ./.;
      snowfall = {
        meta = { name = "initech"; title = "Initech Demo Codebase"; };
        namespace = "initech";
      };
    };
  in lib.mkFlake {
    terranixModule.modules = lib.findDefaultNixFiles ./modules/terraform;
  };

`mkTerranixDerivation`

This function wraps the Terranix terranixConfiguration function and adds utility scripts for Terraform tasks such as building JSON configurations, applying changes, destroying resources, and creating S3 state buckets.

mkTerranixDerivation = { pkgs, system, extraArgs ? { }, modules }:
  let
    terraformConfiguration = inputs.terranix.lib.terranixConfiguration {
      inherit system;
      extraArgs = { inherit lib pkgs; } // extraArgs;
      modules = findDefaultNixFiles ../../modules/terraform ++ modules;
    };

    tf-json = pkgs.writeShellScriptBin "default" ''
      cat ${terraformConfiguration} | ${pkgs.jq}/bin/jq
    '';

    apply = pkgs.writeShellScriptBin "apply" ''
      if [[ -e config.tf.json ]]; then rm -f config.tf.json; fi
      cp ${terraformConfiguration} config.tf.json \
        && ${pkgs.terraform}/bin/terraform init \
        && ${pkgs.terraform}/bin/terraform apply
    '';

    destroy = pkgs.writeShellScriptBin "destroy" ''
      if [[ -e config.tf.json ]]; then rm -f config.tf.json; fi
      cp ${terraformConfiguration} config.tf.json \
        && ${pkgs.terraform}/bin/terraform init \
        && ${pkgs.terraform}/bin/terraform destroy
    '';

    create-state-bucket = pkgs.writeShellScriptBin "create-state-bucket" ''
      BUCKET_NAME=''${1:-"campground-state-bucket"}
      AWS_REGION=''${2:-"us-east-1"}
      echo "Creating S3 bucket $BUCKET_NAME in $AWS_REGION..."
      ${pkgs.awscli}/bin/aws s3api create-bucket \
        --bucket "$BUCKET_NAME" \
        --region "$AWS_REGION" \
        $(if [ "$AWS_REGION" != "us-east-1" ]; then echo "--create-bucket-configuration LocationConstraint=$AWS_REGION"; fi)
      echo "Bucket setup complete."
    '';
  in tf-json // { inherit apply destroy create-state-bucket; };

`pushLambdaToAWS`

This function pushes a Docker image for a Lambda function to AWS Elastic Container Registry (ECR). It handles Docker authentication, tagging, and pushing the image.

pushLambdaToAWS =
  { pkgs, config, lambdaImg, registryName, oci-program ? pkgs.docker }:
  let
    awsRegion = config.provider.aws.region;
    buildPushScript = pkgs.writeShellScriptBin "build-push" ''
      echo "Logging in to ${registryName}"
      ${pkgs.awscli}/bin/aws ecr get-login-password --region ${awsRegion} | \
      ${pkgs.docker}/bin/docker login --username AWS --password-stdin "$1"
      echo "Pushing the Docker image..."
      ${
        lib.initech.pushDockerImage {
          inherit pkgs;
          dockerImage = lambdaImg;
        }
      }/bin/push-docker-image --image-name="$1" --tag="${lambdaImg.imageName}-latest"
    '';
  in
  buildPushScript;

Conclusion

In this post, we explored how to integrate Terranix into a Snowfall-based flake to bridge the gap between Nix’s declarative system and Terraform’s infrastructure-as-code capabilities. By combining Nix’s modular and reusable approach with Terranix, you can simplify infrastructure management, reduce redundancy, and streamline your workflows.

We covered the essentials of using Terranix, from creating basic configurations to leveraging options for module customization. Additionally, we discussed advanced topics like integrating Nix-built artifacts into Terraform workflows, such as Lambda functions or EC2 instances. These techniques demonstrate how tightly coupling Nix and Terraform can yield a more efficient and maintainable infrastructure ecosystem.

Terranix opens new possibilities for unifying application and infrastructure deployments under a single, declarative framework. Whether you’re a seasoned Terraform user or new to Nix, this approach can make managing cloud infrastructure more approachable and powerful.

Looking ahead, I’ll continue exploring how Nix can further enhance cloud infrastructure management. In future posts, we’ll delve into extending these concepts to EC2 deployments and other real-world scenarios. Stay tuned for more insights in the Nix in the Wild series!

Setting Up Authentik and Netbird with Nix

Wed, 01 Jan 2025 00:00:00 +0000

Netbird & Authentik Setup

Setting up NetBird becomes straightforward once you know what you’re doing—but getting to that point can be a pain. In case you’re not familiar, NetBird is an open-source, peer-to-peer VPN solution that simplifies secure network connectivity. It uses WireGuard for encrypted communication and includes a central management platform for configuration and access control. NetBird requires an identity provider, and I chose Authentik because Keycloak was a total pain in the butt to set up and configure. Besides, Authentik is pretty neat and gets the job done without the hassle.

Authentik

The first step is to install Authentik. If you’re using my [dotfiles](https://gitlab.com/usmcamp0811/ dotfiles.git), this should be as simple as enabling it in your system’s configuration file. The module is pretty straightforward and primarily leverages the stock service provided by github:nix-community/authentik-nix.

To get it up and running, a few secrets are required. I manage these the same way I handle all my secrets —using Vault and Vault-Agent to ensure they’re placed in the correct locations on the server. This process is streamlined with a helper service I created, called authentikSecrets, which takes care of moving the secrets where they need to be. Why? Because Authentik has five different services that all seem to rely on the secrets—or at least might, who really knows?

services.authentik = {
  enable = true;
  environmentFile = "${authentikDir}/environmentFile";
  settings = {
    disable_startup_analytics = true;
    avatars = cfg.avatars;
  };
};
systemd.services.authentikSecrets = {
  description = "Get Authentik Secrets";
  serviceConfig = {
    Type = "oneshot";
    User = "root";
  };
  script = ''
    mkdir -p ${authentikDir}
    ${pkgs.coreutils}/bin/cp /tmp/detsys-vault/environmentFile ${authentikDir}/environmentFile
  '';
  wantedBy = [ "multi-user.target" ];
  before = [
    "authentik-migrate.service"
    "authentik-worker.service"
    "authentik.service"
    "authentik-ldap.service"
    "authentik-radius.service"
  ];

};

I generated the AUTHENTIK_SECRET_KEY using a secure random generator, such as openssl rand -base64 32 or python -c "import secrets; print(secrets.token_urlsafe(32))". Other required secrets are primarily for configuring Authentik to send emails to users. In the future, I plan to explore fully automating the setup of users and applications from an existing Authentik configuration. For now, this approach works—stay tuned for a follow-up post where I’ll dive deeper into this process!

Configuring Authentik

As noted earlier, configuring Authentik is a relatively straightforward process, especially when compared to the complexities of Keycloak. To establish the foundational setup, start by creating a user in the admin interface under Directory → Users. Next, navigate to the Applications section to define applications , ensuring the correct provider and credentials are configured. For integrating with NetBird, I followed AuthentiK’s official documentation and Netbird’s official documentation, which was clear and easy to follow. To manage secrets, such as the service account password, I store them in Vault under the NetBird KV, as they are currently only used for this integration.

Netbird

As with most new tools, setting up Netbird with Nix involved some trial and error despite finding a few examples online. While the documentation for Netbird provided a solid overview of its functionality, the specifics of each subservice were not entirely clear—and, to be honest, they still aren’t. However, I’ve learned enough to get things running smoothly for now.

The Management service stands out as the most critical component. It uses gRPC and TCP protocols and listens on a specific path rather than a subdomain. Similarly, the Signal service operates using path prefixing rather than subpathing, much like the Management service. The Dashboard, on the other hand, was a bit confusing. In the Nix module, it doesn’t have its own dedicated port, instead piggybacking on the Management service.

Lastly, there’s the Coturn service, which appears to be optional but is recommended for better connectivity. I haven’t managed to get this fully functional yet, likely due to a configuration issue with my router.

Update: It turns out that the coturn server is required for things to be able to successfully connect. These are the ports you need to make happen on your router unless you modified your server to listen on different ports.

Port	Protocol	Purpose	Required
443	TCP	NetBird Management Plane (HTTPS communication)	Yes
51820	UDP	WireGuard (Peer-to-Peer Data Communication)	Yes
3478	UDP/TCP	STUN/TURN (Primary communication for NAT traversal)	Yes (CoTURN)
3479	UDP/TCP	STUN/TURN (Alternate communication for redundancy)	Optional (CoTURN)
5349	UDP/TCP	TURN (Secure communication with TLS)	Yes (CoTURN)
49152–65535	UDP	Ephemeral Ports (Peer-to-Peer Communication via NAT)	Yes (Dynamic Use Case)
5350	UDP	NAT-PMP (Dynamic Port Mapping on routers, if applicable)	Optional (if enabled)

Cloudflare Proxy Considerations

If you are using Cloudflare as a proxy, you need to enable the gRPC passthrough option for the Management service to function correctly. For details on how to enable this, refer to Cloudflare’s gRPC passthrough documentation. Without this configuration, gRPC traffic will not be routed properly through Cloudflare.

When putting Netbird behind Traefik, many guides suggest additional routes and configurations. However, the Nixpkgs team has simplified this by bundling a robust Nginx configuration with the service. By enabling Nginx in the Nix module and pointing Traefik to the correct host and port, everything should work seamlessly without needing extra proxy configurations.

How to stand-up Vault with NixOS

Sat, 07 Dec 2024 00:00:00 +0000

How to stand-up Vault in a New Environment

This tutorial is how to create a new system and install Vault on it so that we can get other systems to work. This will assume that all that has been installed is a blank NixOS system, real or virtual. This also assumes you are using this repo or at least a fork or some derivation of this repo.

Step 1. Deploy Barebones Archetype

If this is a new system that doesn’t already exist in these dotfiles then we need to create it in ./systems/x86_64-linux/<system hostname> or if its not x86_64-linux use the correct architecture name. I have a template for this scenario. After creating the directory just cd into it and run:

1
2
3

nix flake init --template gitlab:usmcamp0811/dotfiles#new-system
# or if its an Azure VM or some other Virtual Machine maybe try
nix flake init --template gitlab:usmcamp0811/dotfiles#new-azure-vm

Note: You can probably add campground.services.vault to the system config now otherwise after you deploy add it and deploy again.

To deploy the system we can use deploy-rs to get the system config to the new machine. This is super useful if your system is slow such as when its a 2 threaded VM. I have a Nix shell I have created that should have all the things you need already pre-loaded into it. The rest of this tutorial will assume you are in it. To activate this shell just run the following command:

`1`	`nix develop gitlab:usmcamp0811/dotfiles#deploy-shell`

Deploying Barebones config (+ Vault):

`1`	`deploy --hostname <ip\|hostname> --skip-checks /location/of/flake#<new system hostname>`

NOTE: If you have problems with the deploy command you may want to try running it with --ssh-user <your user on the remote machine>. This is because my flake defaults to root and as seen here

Step 2. Initialize & Unseal Vault

Excellent! You now have a new system running. Now lets get Vault setup. I am assuming you deployed Vault to the system above. The following can be run in the deploy-shell anywhere that can reach the newly deployed Vault.

1
2
3

# to see options pass
# init-vault --help
init-vault

NOTE: If you are running this anywhere other than on the system that has Vault running on it you MUST set VAULT_ADDR with the correct location of Vault.

This script will initialize Vault with a single root token and a single unseal key, which are necessary for managing and accessing the Vault. The unseal key is required to “unlock” the Vault after it starts, enabling it to decrypt and serve stored secrets, while the root token provides full administrative access. The init-vault script will securely save these credentials to predefined or user-specified file paths, ensuring they are available for future use. Once initialized, the script will automatically unseal the Vault, making it ready to store and retrieve secrets. This simplifies the process of setting up Vault in a new environment and ensures it is properly configured for secure operations. You are free to re-key the Vault at anytime if your security posture changes and desire more than a single root token.

Step 3. Accessing Vault UI and Configuring Vault

Now that Vault has been initialized we probably want to be able to access our Vault from the WebUI. By default in my config it can be reached from http://0.0.0.0:8200 but if you passed different options to the module when enabling it in your new system, you should use that hostname or ip. In other tutorials I will cover how to setup Traefik so we can use more human readable addresses.

Vault UI

In a web browser navigate to http://new-server-ip:8200. If everything went well you should be presented with the Vault Login page that looks something like this:

Use your root token, found by default at /var/lib/vault/root-token, to login. Once in you can create your KV stores how ever you would like. I have mine setup with a KV version 2 store at secret/campground. You don’t need the UI to do this it can be done with the following shell command, done somewhere that has VAULT_ADDR set correctly and is logged into Vault.

Adding Secrets with the CLI

# in nix develop gitlab:usmcamp0811/dotfiles#deploy-shell

export VAULT_ADDR=http://my-new-hostname:8200
vault login

# provide root token
vault secrets enable -path=secret/mydomain -version=2 kv

# confirm its creation
vault secrets list

# add secrets
vault kv put secret/mydomain/mysecret key1=value1 key2=value2

⚠️ WARNING: Secrets entered via the Vault CLI may be saved in your shell history. To protect sensitive data, consider using environment variables or other secure methods to input secrets.

Adding Policies

Adding policies to your running Vault is effortless if you use the policy-agent option and you place all your policies into a folder in the system config directory. Doing this will run a simple script to add all the policies whenever you update the config. I suggest the following settings when enabling vault:

campground.services.vault = {
  enable = true;
  ui = true;
  storage = {
    backend = "file";
    path = "/persist/vault";
  };
  # This is the secret sauce to get all `*.hcl` files in the `./vault/policies` folder
  # The path is relative to the system's `default.nix`.
  policies = builtins.foldl' (policies: file:
    policies // {
      "${snowfall.path.get-file-name-without-extension file}" = file;
    }) { } (builtins.filter (snowfall.path.has-file-extension "hcl")
      (builtins.map (path:
        ./vault/policies + "/${
          builtins.baseNameOf (builtins.unsafeDiscardStringContext path)
        }") (snowfall.fs.get-files ./vault/policies)));
};

The admin.hcl files should look something like the following:

1
2
3

path "*" {
	capabilities = [ "create", "list", "read", "update", "delete", "patch", "sudo" ]
}

NOTE: The filename becomes the policy name.

You can still add policies through the UI or CLI but depending how you set campground.services.vault.mutable-policies these may be overwritten whenever you redeploy the system. I recommend disabling the mutable-policies and simply relying on the policy-agent to manage your policies because this means you can version your policies along side your system config.

Step 4. Creating Approles

At this point we should have Vault running, secrets created and policies define for those secrets. Now we need to create some approles so that we can have unattended processes/systems get secrets from our Vault in a secure manner. Hashi Corps has good documentation explaining how to create approles, but I have some helper scripts I use to do pretty simply. I suggest naming your approles the same as your system, but how you name your approles is up to you.

1
2
3

# in nix develop gitlab:usmcamp0811/dotfiles#deploy-shell

create-approle my-new-system my-policy

Step 5. Configure NixOS to use an Approle

We now have create an approle for our new system and assigned it a policy appropriate for the role the server is going to serve. We just need to save the secrets somewhere on the new system and tell our NixOS system config about them. The follow must be done on the server assigned the new approle.

1
2
3

# in nix develop gitlab:usmcamp0811/dotfiles#deploy-shell

save-approle-secrets my-new-system

Now that we have our approle saved to our system we can begin to enable the campground.services.vault-agent service on any and all of our systems. The vault-agent service is a simple service that patches SystemD services with secrets retrieved from Vault. This allows us to enable things on our system that might require passwords or sensitive files without hard coding them in our git repo or have them get saved in our world readable Nix store.

# in your new system config

campground.services.vault-agent = {
  enable = true;
  settings = {
    vault = {
      address = "http://my-vault-ip-or-hostname:8200";
      role-id = "/var/lib/vault/<my-approle-name>/role-id";
      secret-id = "/var/lib/vault/<my-approle-name/secret-id";
    };
  };
};

⚠️ WARNING: Make sure you put the correct address, role-id and secret-id! If you don’t it’s not entirely obvious it could take a long time trying to authenticate before finally failing

Migrating from `file` backend to `raft`

If you have deployed your Vault with a file storage backend and you decided that you want to use a raft backend all is not lost! The migration is pretty simple. You just need to make a hcl file that looks like this:

⚠️ WARNING: Make sure you backup your Vault to avoid losing secrets

# migrate.hcl
storage_source "file" {
  path = "/persist/vault/"
}

storage_destination "raft" {
  path = "/persist/vault-raft/"
  node_id = "vault-node-0"
}

cluster_addr = "http://127.0.0.1:8200"

Then just make sure to redeploy your NixOS config with the Vault having raft enabled as the backend storage. When the system finishes switching, stop Vault with systemctl stop vault. Finally you can run:

`1`	`vault operator migrate --config migrate.hcl`

When this finishes start the Vault systemctl start vault then you should be able to unseal the Vault with your previous key(s) and login.

NOTE: As I was figuring this out I had to blow away the /persist/vault-raft directory a couple times and when I recreated it there were some permissions issues that had to be addressed so Vault could write a log file. With any luck you wont have this problem but if you do just check journactl it should give good enough clues that can get you going.

Nix in the Wild: DRYing Out Your Codebase with Reusable Library Functions

Mon, 26 Aug 2024 00:00:00 +0000

DRYing Out Your Codebase with Reusable Library Functions

Welcome back! Last time, we converted our Python projects into Nix packages and built supporting container images without needing to waste time recreating our environment in a Dockerfile. Now, if we scale our codebase to include multiple Python projects, and we want to ensure they all follow a consistent approach—such as exporting a Docker image, and running PyTests—we might consider using a Cookiecutter template and requiring everyone to use it when creating new projects. But what happens when circumstances inevitably change, and we need to update something in that template? As mentioned in previous posts, this would mean modifying a lot of files.

Fortunately, Nix is more than just a configuration language; it’s a fully functional programming language. This allows us to write functions that can simplify these tasks. I could dive into concepts like monads and purely functional programming, but I’ll spare you the detour. The approach you take to writing and using utility functions for your organization is entirely up to you. In this post, I’ll share some ideas and examples of how I’ve been using them to significantly simplify and standardize projects.

Managing Complexity: Simplifying Verbose Nix Expressions

What’s the issue with the verbose nature of how we’ve done things? One advantage is that it offers full control, and those familiar with Nix will understand what’s happening. These are valid reasons to maintain the verbosity in our Nix expressions when packaging Python programs. However, whether to streamline the code is entirely up to you and your organization. If we remember that each default.nix is effectively a single function, then it becomes relevant to consider how we manage complexity within those functions.

Martin Fowler, a well-respected figure in software development, offers an insightful principle regarding function length:

“If you have to spend effort figuring out what a fragment of code does, you should extract it into a function and name it after that ‘what’.” — Martin Fowler

Applying this approach can certainly help junior developers and those unfamiliar with Nix quickly grasp what’s happening, making them more effective. It also helps standardize our projects, ensuring consistency and centralized control across all our work.

Scaling Simplicity: Creating Reusable Functions for Standardized Nix Projects

After discussing the complexity of managing verbosity in Nix expressions, it’s clear that encapsulating common patterns into reusable functions is a key strategy for maintaining simplicity and consistency across projects. Let’s now look at how we can take the principles of reusability and DRY (Don’t Repeat Yourself) and apply them to standardize our Python projects.

For example:

./packages/projects/random_python_project/default.nix

  random-python = pkgs.stdenv.mkDerivation {
    name = "random-python";
    src = ./.;
    phases = [ "installPhase" ];
    installPhase = ''
      mkdir -p $out/src
      mkdir -p $out/bin
      cp -r $src/* $out/src
      cp ${run-app}/bin/run-app $out/bin/random-python
      cp ${run-tests}/bin/run-tests $out/src/run-tests
    '';
    passthru = {
      python = python-env;
      test = run-tests;
      container = container;
    };
  };

./packages/projects/pc_load_letter/default.nix

  pc-load-letter = pkgs.stdenv.mkDerivation {
    name = "pc-load-letter";
    src = ./.;
    phases = [ "installPhase" ];
    installPhase = ''
      mkdir -p $out/src
      mkdir -p $out/bin
      mkdir -p $out/etc
      cp -r $src/* $out/src
      cp ${app_ini} $out/etc/api.ini
      cp ${run-with-wsgi}/bin/run-app $out/bin/run-app-with-wsgi
      cp ${run-tests}/bin/run-tests $out/src/run-tests
    '';
    passthru = {
      python = python-env;
      test = run-tests;
      container = container;
    };
    meta = {
      mainProgram = "run-app-with-wsgi";
    };
  };

The goal is to create a function that abstracts away details like run-tests, container, and possibly python-env, as these are consistent across projects. Additionally, the function should return the mkDerivation with the passthru section already included.

In Nix, function definitions look like this: functionName = x: x * 2 for single arguments, or functionName = {arg1, arg2}: arg1 + arg2 for multiple arguments. Default arguments use this syntax: arg1 ? "defaultValue".

To demonstrate, here’s a hypothetical example where we create a function that adds a text file to every derivation, as one might want to have happen in a Cookiecutter template.

First, we define the function and establish its arguments:

  example-text-file-function =
    {
      pkgs,
      name,
      installPhase,
      mainProgram,
    }:

Next, we create a let ... in block where we define the example text file. This is where we handle all the work that the function needs to perform. We can create files with Nix functions such as writeTextFile or we can import files from the file system.:

    let
      myTextFile = pkgs.writeTextFile {
        name = "example.txt";
        text = "This is some example text for the ${name} Project";
      };
      someFile = ./some-file.yaml
    in

Finally, we output a derivation that uniformly adds the example text files to all derivations:

    pkgs.stdenv.mkDerivation {
      name = "example";
      phases = [ "installPhase" ];
      installPhase =
        installPhase
        + ''
          mkdir -p $out/
          cp ${myTextFile} $out/example.txt
          cp ${someFile} $out/example.yaml
        '';
      meta = {
        inherit mainProgram;
      };
    };

If we now at our organization want to standardize our Python project in an opinionated way so that they are uniform and our developer’s who may be less familiar with Nix can more easily focus on the actual tasks of writing Python and not Nix, we can write a function that looks like the following.

Breaking Down the `mkPythonDerivation` Function

Now that we have a basic understanding of how we can write a function lets begin to write a more complex function to simplify Python development at our organization. Let’s dive into what each part does:

Function Header and Arguments:

mkPythonDerivation = {
  pkgs,
  name,
  src,
  phases ? [ "installPhase" ],
  pypkgs-build-requirements ? { },
  container ? { },
  buildPhase ? "",
  installPhase ? "",
  meta ? { },
}:

We define the function with several customizable arguments. The key parameters include:

pkgs: The package set, providing access to all the Nix packages.
name: The name of the derivation also used to give a name to the container this creates.
src: The source code directory where our pyproject.toml is located.
phases: By default, this includes only the installPhase, but it’s configurable.
pypkgs-build-requirements, container, buildPhase, installPhase, and meta: Optional configurations to fine-tune how the derivation behaves. The defaults for these were taken from what we had used in our previously in our Python packages and I think are reasonable enough to work for most cases.

Handling Container Defaults:

let
  defaultContainer = {
    tag = "latest";
    contents = [ python-env ];
    config = {
      Entrypoint = [ "${python-env}/bin/python" ];
    };
  };
  finalContainer = defaultContainer // container;

We define a defaultContainer configuration, which ensures every Python project has a consistent container setup. The final container is a merge of this default and any custom settings passed in via the container argument. Note that the default container this creates returns a container with just the project’s Python environment and will simply start a REPL.

Overriding Poetry Dependencies:

p2n-overrides = pkgs.poetry2nix.defaultPoetryOverrides.extend (
  self: super:
  builtins.mapAttrs (
    package: build-requirements:
    let
      override = super.${package}.overridePythonAttrs (oldAttrs: {
        buildInputs =
          (oldAttrs.buildInputs or [ ]) ++ (builtins.map (req: super.${req}) build-requirements);
      });
    in
    override
  ) pypkgs-build-requirements
);

We use poetry2nix to manage Python dependencies, allowing for custom overrides. This block is the part from our Python packages that handles edgecases. I am incorporating it into the function so that we can hope to abstract this part away as much as possible while still handling them. I understand the average developer who uses this might not fully understand all of Nix and so this helps to keep things simpler (or so I hope).

Creating the Python Environment:

python-env = pkgs.poetry2nix.mkPoetryEnv {
  projectDir = src;
  python = pkgs.python311;
  overrides = p2n-overrides;
  preferWheels = true;
};
extended-python-env = python-env.withPackages (
  ps: with ps; [
    bpython
    pytest
    ipykernel
  ]
);

We define a python-env with dependencies using poetry2nix. To avoid including development tools like pytest, bpython, and ipykernel in our deployment builds, we create an extended-python-env specifically for development and testing. This environment includes these tools, ensuring they are available during development without affecting production builds.

Utility Scripts for Common Tasks:

run-bpython = pkgs.writeShellScriptBin "run-bpython" ''
  export PYTHONPATH=${python-env}/lib/python${pythonVersion}/site-packages:${src}
  ${extended-python-env}/bin/bpython "$@"
'';
run-jupyter = pkgs.writeShellScriptBin "run-jupyter" ''
  export
  PYTHONPATH=${pkgs.jupyter-all}/lib/python${jupyterPythonVersion}/site-packages:${python-env}/lib/python${pythonVersion}/site-packages:${src}
  ${pkgs.jupyter-all}/bin/jupyter console "$@"
'';
run-tests = pkgs.writeShellScriptBin "run-tests" ''
  export PYTHONPATH="${python-env}/lib/python${pythonVersion}/site-packages:${src}"
  ${extended-python-env}/bin/pytest ${src}/tests/ "$@"
'';

We create scripts for running bpython, jupyter, and tests. These scripts standardize how developers interact with the environment, reducing friction and improving consistency across projects.

Building the Container:
1 2 3 4

container = pkgs.dockerTools.buildLayeredImage { name = pyDerivation.name; inherit (finalContainer) tag contents config; };
The container configuration is turned into a Docker image using dockerTools.buildLayeredImage, ensuring every project has a container aligned with our standardized setup.

The Main Derivation:

pyDerivation = pkgs.stdenv.mkDerivation {
  name = name;
  src = src;
  phases = phases;
  buildPhase = buildPhase;
  installPhase =
    ''
      mkdir -p $out/src
      mkdir -p $out/bin
      cp -r $src/* $out/src
      cp ${run-tests}/bin/run-tests $out/src/run-tests
    ''
    + installPhase;
  passthru = {
    python = python-env;
    bpython = run-bpython;
    jupyter = run-jupyter;
    test = run-tests;
    container = container;
  };
  meta = meta;
};

The core of the function is the mkDerivation, which handles the actual build process. We include common setup steps, like copying source files and ensuring the test script is available. The passthru section makes all our utility scripts and container accessible in the final derivation.

Returning the Derivation:
1 2

in pyDerivation;
Finally, the derivation is returned, completing the function. The complete code for this function can be found here

Using `mkPythonDerivation` in our Codebase

If we take a look at the pc-load-letter project, you’ll notice the configuration is much cleaner now, even though this is the more complex of the two example Python projects since it needs to run using uWSGI. Let’s focus on what has changed in the default.nix file:

  pc-load-letter = mkPythonDerivation {
    inherit pkgs name src;
    installPhase = ''
      mkdir -p $out/etc
      cp ${app_ini} $out/etc/api.ini
      cp ${run-with-wsgi}/bin/run-app $out/bin/run-app-with-wsgi
    '';
    container = {
      inherit name;
      tag = "latest";
      contents = [ run-with-wsgi ];
      config = {
        Entrypoint = [ "run-app" ];
      };
    };
    meta = {
      mainProgram = "run-app-with-wsgi";
    };

Notice how adding app_ini and run-with-wsgi to the installPhase is nearly all that’s needed. The installPhase is where you define the steps to prepare your package for deployment. In this case, it simply copies the necessary configuration files and scripts to their correct locations within the container.

The container section only needs to define the Entrypoint and contents, pointing to the run-with-wsgi script we created in our previous post. The Entrypoint is what the container will execute when it starts, and contents lists all dependencies or files that need to be present in the container.

Here’s where the declarative nature of Nix really shines. By writing down everything your project requires in a straightforward way, like listing out dependencies and scripts, Nix automatically handles the rest. The process is declarative because you’re simply describing what you need (e.g., files, scripts, dependencies) without worrying about how they get added. Nix ensures the environment is set up with exactly what you’ve declared and nothing more.

Lastly, the run-app-with-wsgi script is named differently from the main project’s name. To handle this, we specify it in meta.mainProgram, which tells Nix what to run when executing the container. While renaming the script to match the project’s name could’ve worked, I kept the original name to show how to handle cases where the script name doesn’t match the project name.

This mkPythonDerivation function abstracts away much of the complexity, allowing developers to focus on writing Python code while providing a consistent and standardized build environment. By adopting this approach, I compared the lines of code before and after using the function and found that it reduces our codebase by 37 to 50 lines per Python package. Additionally, it ensures that our Python packages adhere to a consistent delivery standard.

This is a prime example of how Nix’s functional programming capabilities can significantly DRY up a codebase while still offering flexibility and control. This approach isn’t limited to just Python projects; it can be applied to any type of software. For instance, I created a similar function for the Flink jobs in our repository. Although that function ended up being a bit lengthy—over 100 lines—due to the complexity it abstracts, developers now only need to write 4 lines of Nix code to develop and package a Flink job. By encapsulating common patterns into reusable functions, we achieve both simplicity and standardization across the project, all while leveraging Nix’s powerful and declarative framework.

This example illustrates how reusable functions in Nix can simplify a wide range of scenarios, not just Python packaging. Whether it’s Python, Flink, or any other software component, the principles remain the same: by centralizing common patterns into concise functions, we can reduce redundancy, improve maintainability, and ensure consistency across an entire codebase.

Wrapping it up

To wrap things up, embracing reusable functions in Nix allows you to significantly DRY out your codebase while keeping everything standardized and easy to manage. Not only do these functions reduce the lines of code across projects, but they also abstract away complexity, making the onboarding process easier for new developers and ensuring that changes to your infrastructure are painless and scalable.

The true strength of Nix lies in its flexibility combined with its declarative approach. By leveraging Nix’s functional programming features, you can tailor your development environment precisely to your needs, enforcing best practices across the board. While this post focused on Python projects, the same principles can be applied to various other types of software within your organization, allowing you to standardize without losing the control and customization that Nix offers.

I encourage you to explore further, experiment with writing your own reusable functions, and discover how they can simplify your workflow while enhancing consistency and reproducibility across your projects. To see exactly how these concepts were applied in practice, you can review the code changes introduced in this blog post by checking out the merge request linked below.

Nix in the Wild: Packaging Python Projects and Building Containers

Wed, 07 Aug 2024 00:00:00 +0000

Packaging Python Projects and Building Containers with Nix

Welcome back! In our last post, we integrated Nix into our codebase by setting up flake.nix with the Snowfall library and configuring a simple default devshell. While we could continue enhancing our devshells to include all necessary programs and environment variables, this approach has its limitations. Devshells ensure that specified tools and settings are installed, but they aren’t fully isolated from the system’s environment. This means developers can still use programs or environment variables outside the shell’s scope, which can undermine reproducibility by introducing inconsistencies into the development workflow. In my opinion, devshells are excellent for setting up an environment for interactive development or testing. However, they should not be solely relied upon as the runtime environment for your software.

So, what should we do? You might be wondering, “Isn’t the whole point of using Nix to make our software reproducible?” The answer is yes, it is! However, to achieve true reproducibility, we need to go beyond just specifying the tools we want available in our environment. We must use Nix to define precisely how our software should be built and run, ensuring every aspect is controlled and predictable. In this post, I’ll demonstrate how we can take our existing Python projects, convert them into Nix packages, and create Docker images. This approach not only allows us to run our tests without cloning repositories or managing dependencies manually but also ensures that all we need is Nix installed and configured. By the end, you’ll see how Nix can fully encapsulate our software’s runtime, providing a reproducible and reliable environment.

Why Package Python Projects with Nix?

This is a real-world situation that happened just last week. We have a Python project nested in a Git repository, similar to the ones in the Initech repo. The Python project uses a virtual environment managed by Poetry, and everything usually works fine. However, when a developer got a new computer and tried to install the virtual environment with poetry install, they encountered issues with the numpy package. They tried using both the system Python and the one specified in our devshell, but the problem persisted. After some debugging, we discovered that Poetry was trying to install the environment with Python 3.12 (the system Python) instead of 3.11, causing compatibility issues with some dependencies. Although we had the correct Python version in the devshell, there was nothing explicitly instructing Poetry to use it, leading to wasted time troubleshooting. At least two hours of work were spent resolving this problem, not to mention the additional time spent debugging a broken Docker build caused by changes to the pyproject.toml to make it work on the developer’s machine. While it’s easy to dismiss this as a typical business cost, it doesn’t have to be this way. We have tools that can practically eliminate this problem.

If we had been using Nix to manage the virtual environment, we wouldn’t have encountered these issues. We could have used poetry2nix to translate the poetry.lock file into Nix expressions, ensuring that the exact dependencies and Python version were consistently used. This would have prevented the compatibility issues we faced when Poetry tried to install the environment with Python 3.12 instead of 3.11, and the changes to the pyproject.toml needed to make it work on the developer’s machine wouldn’t have broken the Docker build. Moreover, Nix’s benefits extend beyond Python, as similar tools exist for other languages, allowing Nix to provide consistent and reproducible builds across different technology stacks. By packaging projects with Nix, developers can ensure that the entire environment, from dependencies to specific language versions, is controlled and predictable. This not only saves time and effort but also significantly reduces the risk of environment-related bugs and deployment issues.

Setting Up Python Projects as Nix Packages

Packaging Python projects with Nix is straightforward, especially with Poetry. While the NixOS Wiki provides detailed documentation on building Python packages without Poetry, this discussion focuses on using Poetry for its simplicity and versatility. In this post, we’ll package the pc-load-letter Flask app as an executable Nix package. For other projects, like the random-python-project and Flink jobs, we’ll cover in an upcoming post. By the end, you’ll be able to run the pc-load-letter Flask app in production mode with a single command, without needing to install anything, while retaining access to the Python interpreter for interactive development.

Adding `poetry2nix` to our Flake

To use poetry2nix in our project, we need to make a few additions to our flake.nix file. Specifically, we’ll add poetry2nix to the inputs section and include its overlay in the overlays list. Below are the key changes you need to make:

In the inputs section, add:

`1`	`poetry2nix.url = "github:nix-community/poetry2nix";`

In the overlays list, add:

`1`	`poetry2nix.overlays.default`

These changes integrate poetry2nix into our Nix environment, enabling us to manage Python dependencies defined in a poetry.lock file. Your flake.nix should include these additions alongside your existing configurations.

To Move the Projects or Not to Move Them: That Is the Question

The next step involves a decision: should you move your Python projects into the packages directory or leave them in their original location? Currently, all Python projects are housed in a /projects directory. You can keep them there, move the entire /projects directory into the /packages directory, or choose any other organizational structure that suits your needs. For the demo project, I will be moving the projects directory into packages.

If you decide to leave them in place, you’ll still need to create a parallel file structure within /packages, including at least a default.nix for each project. Personally, I believe that moving everything to the packages directory is the best option, as it provides better organization. However, the choice is entirely up to you; I just wanted to ensure you’re aware of the different options available.

Packaging

To create a minimal package within a Snowfall flake, start by creating a directory named after the package, such as packages/projects/pc_load_letter. Inside this directory, create a default.nix file. For a basic setup, this file can contain a simple derivation using the mkDerivation function. For example, the default.nix file might include a derivation that specifies the package name and source directory. This minimal example sets the foundation for creating a package, though it is unconfigured and does nothing functional.

{
  pkgs,
  ...
}:
let
  pc-load-letter = pkgs.stdenv.mkDerivation {
    name = "pc-load-letter";
    src = ./.;
  };
in
pc-load-letter

Creating the Python Environment

Since this is a Python program, the first step is to set up a Python virtual environment. For a simple project, you can do this with the following:

python-env = pkgs.poetry2nix.mkPoetryEnv {
  projectDir = ./flask/.;
  python = pkgs.python311;
};

Note: projectDir should point to the directory containing the pyproject.toml file.

To make the Nix package use the Python environment defined by the pyproject.toml, you can replace the pc-load-letter derivation with python-env in the default.nix file. This setup is similar to using poetry run python, allowing you to run your Python environment. However, Nix can do more than just this; it can make nix run .#pc-load-letter actually execute your entire application.

Handling an Edge Case

Creating a Python environment with the provided configuration is usually sufficient. However, there are some “edge cases” that may require additional steps due to inconsistencies in the Python package ecosystem. For instance, some packages, like setuptools, may need to be installed before other packages. The poetry2nix documentation offers guidance on handling these scenarios.

One example of such an edge case is with the random-python-project. You might not know there is an issue until you try to build the Python environment and encounter an error. As shown in the image below, look for the highlighted portion to identify the problem. In this case, the snaptime package required setuptools to be pre-installed. To resolve this, we need to pass an override to poetry2nix. The following configuration can handle multiple edge case packages if needed:

pypkgs-build-requirements = {
  snaptime = [ "setuptools" ];
};

p2n-overrides = pkgs.poetry2nix.defaultPoetryOverrides.extend (
  self: super:
  builtins.mapAttrs (
    package: build-requirements:
    let
      override = super.${package}.overridePythonAttrs (oldAttrs: {
        buildInputs =
          (oldAttrs.buildInputs or [ ]) ++ (builtins.map (req: super.${req}) build-requirements);
      });
    in
    override
  ) pypkgs-build-requirements
);

python-env = pkgs.poetry2nix.mkPoetryEnv {
  projectDir = ./.;
  python = pkgs.python311;
  overrides = p2n-overrides; #<-- Don't forget to add it here
  preferWheels = true;
};

This Nix code snippet sets up a Python environment with custom build requirements using poetry2nix. It starts by defining a dictionary (pypkgs-build-requirements) that specifies additional packages needed for building certain Python packages. For example, the snaptime package requires setuptools to be pre-installed. Next, it creates p2n-overrides, which extends the default Poetry overrides provided by poetry2nix. This extension involves iterating over the pypkgs-build-requirements dictionary and modifying each package’s buildInputs to include the necessary dependencies. The overridePythonAttrs function is used to update the buildInputs attribute, ensuring that if buildInputs is not already defined, it defaults to an empty list. The dependencies are then mapped to their corresponding Nix packages using builtins.map, ensuring they are included during the build process. This setup ensures that all specified build requirements are met when creating the Python environment.

How to Run the App

The fundamental point I want to emphasize is that we use Nix not just to define our dependencies but also to specify how to run our software. While tools like Poetry list the necessary dependencies for our Python applications, that’s often not sufficient. It’s crucial to define both what we need and how to use it. With Nix, we can go a step further and explicitly detail how to run our code, ensuring consistency and reproducibility in every environment.

For instance, the pc-load-letter application is a Flask app, and Flask apps typically require a WSGI server like uWSGI to run efficiently. We need to ensure that our Nix package includes this setup or is compatible with it. In the existing Dockerfile for this app, we’ve been using the following CMD:

`1`	`CMD ["/root/.local/bin/uwsgi", "api.ini"]`

With Docker, this command is specified separately in a Dockerfile alongside other setup instructions. While Docker containers provide a consistent environment for packaging and running applications, the configuration can be spread across various files and formats. If you’ve never had to install uWSGI in a container compiled with the correct version of Python, you may not fully appreciate the challenges involved. This process can be particularly difficult, especially if you’re not familiar with WSGI configurations.

In contrast, Nix allows us to define everything—including dependencies, environment setup, and run commands—in a single declarative language and file. This provides a more integrated approach, where all aspects of the application’s build and runtime environment are managed together. This unified configuration ensures that our application runs consistently, no matter where it is deployed, without relying on additional tools or scripts.

Since the api.ini file is supposed to have a path to our Python code, we will move this configuration into the default.nix file. This allows us to use Nix’s path interpolation to dynamically generate the correct path to the Python code in the Nix store. The configuration looks like this, using a Nix function to create text files in the Nix store:

app_ini = pkgs.writeText "api.ini" ''
  [uwsgi]
  wsgi-file = ${src}/pc_load_letter/app.py
  callable = app
  http = :8080
  processes = 4
  threads = 2
  master = true
  chmod-socket = 660
  vacuum = true
  plugins = python3
  die-on-term = true
'';

Once we have added the app.ini file to our Nix default.nix file, we can declare the WSGI app we want to use. This is straightforward:

uwsgi = pkgs.uwsgi.override {
  python3 = python-env;
  plugins = [ "python3" ];
};

Notice that we specify the Python environment to use, which we defined earlier with poetry2nix. This integration ensures that the correct Python environment is used, avoiding inconsistencies and making the setup more robust.

Next, we’ll create a script to run the application using a Nix function. Here’s the code snippet:

run-with-wsgi = pkgs.writeShellApplication {
  name = "run-app";
  text = ''
    export PYTHONPATH="${python-env}/lib/python${builtins.substring 0 4
    python-env.python.version}/site-packages"
    ${uwsgi}/bin/uwsgi --ini ${app_ini}
  '';
};

In this script, we use the ${} syntax for string interpolation, which allows Nix to automatically insert the correct paths from the Nix store. The Nix store is just the location at /nix/store where Nix stores all packages and dependencies. Specifically, ${python-env} and ${uwsgi} are placeholders that get replaced with the exact paths to the Python environment and the uwsgi binary, respectively, within the Nix store. Additionally, we set the PYTHONPATH environment variable to ensure that uwsgi can access our specified Python environment, including all necessary libraries.

This use of string interpolation ensures that all file paths are precise and consistent with the specific versions and configurations in the Nix store, providing a reliable and reproducible setup for running the application.

So at this point we can have our default.nix return run-wish-wsgi and we could be done and that would look like this:

{ pkgs, ... }:
let

  src = ./flask/.;

  python-env = pkgs.poetry2nix.mkPoetryEnv {
    projectDir = src;
    python = pkgs.python311;
  };

  uwsgi = pkgs.uwsgi.override {
    python3 = python-env;
    plugins = [ "python3" ];
  };

  run-with-wsgi = pkgs.writeShellApplication {
    name = "run-app";
    text = ''
      export PYTHONPATH="${python-env}/lib/python${builtins.substring 0 4
      python-env.python.version}/site-packages"
      ${uwsgi}/bin/uwsgi --ini ${app_ini}
    '';
  };

  app_ini = pkgs.writeText "api.ini" ''
    [uwsgi]
    wsgi-file = ${src}/pc_load_letter/app.py
    callable = app
    http = :8080
    processes = 4
    threads = 2
    master = true
    chmod-socket = 660
    vacuum = true
    plugins = python3
    die-on-term = true
  '';
in
run-with-wsgi

You would then be able to do the following command and have the Flask app running on port 8080.

`1`	`nix run .#pc-load-letter`

Providing a Python Interpreter via `passthru`

Running an application with a single command without additional installations is ideal. However, there are times when access to a Python REPL or the underlying Python interpreter is necessary for other tasks. To enable this, we can add a passthru attribute to our default.nix using pkgs.stdenv.mkDerivation.

The mkDerivation function sets up a folder structure in the Nix store. We need to specify the src attribute, which points to the current directory, and use the installPhase to organize our application and its source code. While the structure can be flexible, it is advisable to follow a standard layout—for example, using bin for binaries/executable files and src for source files. The mkDerivation function provides special variables like $src and $out. $out represents the root of the derivation in the Nix store, and $src refers to the source path defined by src = ./.. To make our source code accessible when building this package, we place it in the $out/src directory. The executable for the run-with-wsgi application should be placed in the $out/bin directory.

The passthru attribute is used to expose additional information or dependencies that are not directly involved in building the package but are useful for other purposes. Here’s an example of how to include a Python environment:

pc-load-letter = pkgs.stdenv.mkDerivation {
  name = "pc-load-letter";
  src = ./.;
  phases = [ "installPhase" ];
  installPhase = ''
    mkdir -p $out/src
    mkdir -p $out/bin
    cp -r $src/flask/* $out/src
    cp ${run-with-wsgi}/bin/run-app $out/bin/run-app-with-wsgi
  '';
  passthru = {
    python = python-env;
  };
  meta = {
    mainProgram = "run-app-with-wsgi";
  };
};

In this example, python-env represents the Python environment we want to expose. By including python = python-env; under the passthru attribute, we make this environment available.

It is important to note that meta.mainProgram is necessary if the main executable’s name differs from the value specified in the name attribute. With this configuration, users can access the Python interpreter for development, debugging, or running additional scripts. This setup enhances the package’s versatility by providing not only the main application but also the necessary tools for various tasks.

Simplifying Testing

With our package now in a stable, production-ready state, and equipped with various tools for development and alternative use cases, let’s focus on testing. As professional software developers, we understand the importance of writing and executing tests. However, specifying the correct way to run tests in Merge Requests can often lead to confusion, whether it’s about the right directory to execute PyTest from or ensuring the PYTHONPATH is correctly set. These issues can cause inconsistencies and frustrations.

Testing should be straightforward, accessible to the entire team, and seamlessly integrated into our CI/CD pipelines. While I can’t improve the quality of your tests, I can help streamline the process of running them, making it as effortless as possible. Let’s remove any barriers and simplify testing for everyone.

To start, we can define how to run our tests using Nix. We can add a script to our default.nix file that outlines the steps needed to execute our tests. Since we’re using PyTest, we just need to set the PYTHONPATH and specify the directory containing our tests. Here’s an example script for our pc_load_letter project:

run-tests = pkgs.writeShellScriptBin "run-tests" ''
    export PYTHONPATH="${python-env}/lib/python${
      builtins.substring 0 4 python-env.python.version
    }/site-packages:${src}"
    ${python-env}/bin/pytest ${src}/tests/ "$@"
'';

Note: The "$@" at the end allows for additional arguments to be passed.

Next, we add this script as a passthru in the mkDerivation function, similar to how we did with python-env. Now, to run the tests, you can simply use the command:

nix run .#pc_load_letter.test

# or for more verbose testing

nix run .#pc_load_letter.test -- -vvv

This is really simple—let’s do this for all of our projects! If we want to automate our testing in CI, writing nix run .#<package name>.test for every project can become tedious, especially as new projects are added. Fortunately, we can simplify this process further by using Nix Flakes’ checks feature, which allows us to define tests for each package and validate code across different environments and setups.

For example, we can create a folder checks/pc_load_letter at the root of the project with a default.nix file that specifies the testing procedure. While you probably could have include the PyTest script here, but I decided to just leave it in the package, which makes this check pretty simple:

{ pkgs, ... }:

pkgs.runCommand "pc_load_letter" { src = ./.; } ''
  mkdir -p $out
  ${pkgs.initech.pc_load_letter.test}/bin/run-tests > $out/results.txt
''

By following this pattern for every package in the flake, you can run:

`1`	`nix flake check`

to execute all tests with a single command, making the process much simpler. We will cover more of the intricacies of hooks in future posts.

Building Docker Images

It’s great that we can run a Flask app with a single command, but let’s be honest—these days, everything’s about Kubernetes. That means we need a Docker container, and some might think this whole Nix thing is just a novelty. Well, that’s nonsense because Nix builds Docker images better than Docker itself!

I’ve been using Docker since 2016 and have spent countless hours trying to containerize everything imaginable. Working in air-gapped environments often meant that if I needed a tool, I had to either containerize it or go without. I’ve containerized everything, from terminal emulators to web browsers, to use them on air-gapped computers. However, it wasn’t until I started using Nix last summer that I realized I had it all wrong. My life would have been a million times easier if I had just been using Nix from the start.

Typically, with Docker, we’d find an appropriate base image, like Ubuntu or a Python image. If you’re in an organization, you probably want to control which base images are used to ensure security best practices are followed. This is what I aimed to simulate with the Initech base Python image. Once you have a base image for your organization, the teams need to use it and add their tools' dependencies. This could be straightforward, like running apt install for a few packages, or it could get complicated when you need something that’s not in the Ubuntu or Red Hat repos (which happens often). Then, you face a long development cycle to build out the image.

Here’s an example of what can happen: you have a Docker image with a Python app or maybe Jupyter, and you need to update the version of openssl due to security concerns. This requires updating the base image, which means updating to a newer version of Ubuntu, changing apt repos, and possibly dealing with a different Python version. Suddenly, you’re stuck updating all your Python dependencies because you’ve uncovered a tangled mess. Next thing you know, you’re two or three sprints in and still struggling to get the image working as expected. Let’s be real—you know this has happened to you. So enough talking about how great Nix is at containers—let’s just do it already.

Add this to the default.nix:

container = pkgs.dockerTools.buildLayeredImage {
    name = "pc-load-letter";
    tag = "latest";
    contents = [ run-with-wsgi ];
    config = {
      Entrypoint = [ "run-app" ];
    };
};

Then add it to the passthru of your mkDerivation and you’re done.

You can build your image by simply doing:

`1`	`nix build .#pc-load-letter.container && docker load -i ./result`

You can run the image and confirm I’m not blowing smoke by doing:

`1`	`docker run -it --rm -p 8080:8080 pc-load-letter:latest`

You’ll find the Flask app in your browser at http://localhost:8080.

As you can see, this approach is far more concise than writing a Dockerfile! Plus, you get some added benefits that your security department will appreciate. The resulting Docker image contains only the exact components your application requires—nothing more, nothing less. There’s not even a shell, significantly reducing your attack surface compared to an imperatively configured Dockerfile that might include extra packages for tasks like extracting or building files. Another nice feature of Nix-built Docker images is that they maximize the reuse of image layers between different images. This optimization reduces the disk space required by your container registries, making them more efficient.

Wrapping Up

We’ve explored a comprehensive workflow for packaging Python projects with Nix, creating Docker images, and ensuring reproducibility across environments. By leveraging Nix, we can achieve a fully declarative setup that eliminates “it works on my machine” issues and streamlines the deployment process.

Key Takeaways:

Environment Consistency: Nix allows us to define precise environments, ensuring all dependencies, including specific versions of Python and packages, are consistently used across systems. This prevents common issues caused by system discrepancies.
Integrated Tooling: Tools like poetry2nix simplify the translation of a poetry.lock file into Nix expressions, seamlessly managing Python dependencies. This also enables the integration of application-specific configurations directly into the Nix setup, avoiding pitfalls associated with manually managed configurations.
Simplified Deployment: By defining how to run software in Nix, we can package dependencies and ensure the application runs as expected, making it particularly beneficial for complex environments.
Efficient Testing and CI Integration: Nix’s checks feature streamlines the testing process, making it easy to run tests consistently and integrate them into CI/CD pipelines.
Containerization with Nix: Building Docker images using Nix offers a secure and efficient alternative to traditional Dockerfiles. Nix-built images include only the necessary components, reducing the attack surface and optimizing storage through layer reuse.

Adopting Nix for packaging and containerization provides a robust, reproducible, and maintainable setup that enhances development workflows and deployment practices. Whether you’re working with Python, other languages, or mixed technology stacks, Nix offers a versatile solution for managing your software’s lifecycle.

This post focused on the pc_load_letter project, but the steps outlined are applicable to other Python projects and similar for other languages. You might be thinking, “The default.nix file is 75 lines—much longer than my typical Dockerfile.” In the next post, we’ll explore how to streamline the default.nix file and standardize configurations using Nix library functions.

Thank you for joining me on this journey through Nix in the wild. Subscribe for more insights as we delve into hooks, advanced packaging techniques, and more. Happy hacking!

Nix in the Wild: Nixing Your Codebase

Sat, 03 Aug 2024 00:00:00 +0000

Nix in the Wild: Nixing Your Codebase

Welcome back to the ‘Nix in the Wild’ series. In this post, we’ll dive into the practical steps of integrating Nix into your existing codebase. We’ll establish the foundational elements, including creating a flake.nix file and setting up the directory structure necessary for the Snowfall library. Additionally, we’ll create our first Nix shell to help teams standardize their development environments. I’ll also share some lessons learned from my experience with Nix, discussing why I chose Snowfall, what I appreciate about it, and what I’d like to see improved. Let’s dive in and start ’nixing’ our codebase.

Setting Up Nix with Flakes

To follow along, ensure you have Nix installed from the previous post. If you haven’t already, you need to enable Flakes by adding the following line to your Nix configuration file:

`1`	`experimental-features = nix-command flakes`

This can be done in ~/.config/nix/nix.conf or /etc/nix/nix.conf.

What Are Flakes?

Flakes are a relatively new feature in Nix, currently classified as experimental. Despite this, they’re expected to become a standard part of Nix due to how useful they are. Flakes simplify version management for Nix packages and make it easier to utilize external resources. For a more detailed explanation, check out Jake Hamilton’s YouTube video.

In this series, I’m using the Initech demo repo, a monorepo designed to simulate a full organizational codebase. When working with Flakes, it’s important to note that there’s a one-to-one mapping between a Flake and a Git repository. Nix can only recognize files in a Flake if they are tracked by Git. So, if you encounter errors, check if the relevant files are added to Git. Remember, you don’t need to commit changes immediately—just ensure the files are tracked.

Why Use a Monorepo?

For the Initech demo, I’ve chosen a monorepo setup for its convenience and numerous benefits in managing multiple small projects. Monorepos are particularly advantageous when dealing with platforms or a large number of systems, as they streamline code reuse and eliminate the need for frequent updates to lock files. The choice between a monorepo and a polyrepo depends on specific project needs and personal preference. However, I’ve found that monorepos greatly simplify management, especially in scenarios involving multiple systems and smaller projects.

If a monorepo doesn’t suit your organization but you have several interconnected components, consider creating a Flake that acts as an aggregator for all your organization’s Flakes. This approach allows you to precisely version the interaction of sub-projects and facilitates integration checks in your CI pipeline with minimal commands.

Setting Up `flake.nix`

Now, let’s start setting up our codebase with Nix. In the root of the Initech repo, we’ll create a flake.nix file using the following command. The flake.lock file will be autogenerated later.

`1`	`nix flake init`

Why Use Snowfall Lib?

While it’s not mandatory to use Snowfall Lib for structuring your Flakes, I’ve found it to be incredibly helpful. Snowfall is an opinionated library designed for Nix Flakes, which can be particularly advantageous when you’re starting out. By providing a recommended folder structure, it minimizes the complexity of setting up your project and reduces the number of decisions you need to make. Snowfall handles the “glue code” required for importing modules into your Flake and overall just makes it easier to manage your setup. I’ve successfully used Snowfall to manage a range of systems in my homelab and various work projects.

Here’s an example of a basic flake.nix with no configuration that you get from the above command:

{
  description = "A very basic flake";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
  };

  outputs = { self, nixpkgs }: {
    packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
    packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
  };
}

Configuring Inputs

Next, we’ll add the Snowfall Lib repository to the inputs section. Additionally, it’s a good idea to specify the current stable branch of nixpkgs and an unstable branch for flexibility in choosing packages. You can manage this selection using overlays, which we will cover later. Here’s an example of what your inputs might look like:

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
  unstable.url = "github:nixos/nixpkgs?ref=nixos-unstable";

  snowfall-lib = {
    url = "github:snowfallorg/lib";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

Defining Outputs

Earlier in this post, we introduced a basic example of defining outputs in a Nix Flake:

outputs = { self, nixpkgs }: {
  packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
  packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
};

In this example, the outputs attribute is defined as a function that takes two arguments: self and nixpkgs. The function then returns a set of packages, specifically two Linux packages: hello and default. This simple function demonstrates how outputs can be constructed based on the inputs provided to the function.

Now, we’ll transition from this basic setup to a more sophisticated one using the mkFlake function from the Snowfall Lib. This library provides a standardized way to define outputs, making it easier to manage complex configurations. Instead of manually specifying the outputs, we leverage mkFlake to automate and streamline the process.

Here’s how we use Snowfall Lib to define our outputs:

outputs = inputs:
  inputs.snowfall-lib.mkFlake {
    inherit inputs;
    src = ./.;

    # Configure Snowfall Lib. All settings are optional.
    snowfall = {
      # Specify the directory for your Nix files.
      root = ./.;

      # Define a namespace for your flake's packages, libraries, and overlays.
      namespace = "initech";

      # Add metadata that can be utilized by tools like Snowfall Frost.
      meta = {
        # A slug for documentation, typically used in file paths.
        name = "initech";

        # The title for your flake, often the project's name.
        title = "Initech Demo Codebase";
      };
    };
  };

In this setup, the outputs function uses the inputs to call mkFlake, a utility function provided by Snowfall Lib. The mkFlake function simplifies configuration by managing common tasks and structures, allowing you to focus on higher-level configurations. It generates outputs based on the provided inputs, such as Nix packages and any additional input Flakes. Because mkFlake is opinionated about the folder structure, it can automatically stitch everything together. This results in outputs that export all packages, define multiple computer systems, and set up user profiles—all without the need for custom plumbing. This approach not only reduces boilerplate but also ensures consistency across different projects. By adopting Snowfall Lib, you can streamline your development process, particularly in environments with multiple systems and components.

Organizing the Project with Snowfall

In this section, I’ll give a quick rundown of the various directories. I’ve noticed that when introducing Nix to an existing codebase, people often wonder why these new directories suddenly appear and what they’re for, especially if they’re only vaguely familiar with the reasons for adopting Nix in the first place. Understanding the role of each directory will help make the structure and purpose of the setup clearer. For more details, the Snowfall documentation is excellent and can be found here.

Snowfall Directory Structure

This structure for me has generally gone at the root of the git project but it is possible to move it elsewhere in the project. The Snowfall docs have ./nix as being their example location. Below is a high level overveiw of what the structure of our projects will look like once we add Snowfall and Nix.

Root Directory

flake.nix: Your Nix Flake definition.
flake.lock: The lock file that tells Nix what versions of nixpkgs and other Flakes to use.

Library Functions

lib/ (optional): This directory is designated for custom library functions. It can contain helper functions to standardize common tasks or reduce boilerplate code. With Nix being a programming language, the possibilities are extensive.
- default.nix: If you choose to add additional library functions, they would go here. This file defines an attribute set that merges with the existing lib.

Package Definitions

packages/ (optional): This directory is where we define the packages that our Flake can export. These packages don’t have to be large or complex; they can be as simple as a script that performs a specific task and needs to be easily accessible to others. Alternatively, you can use this space to repackage existing software that isn’t already available in the Nix ecosystem. We’ll cover more on this topic in later blog posts.
- <package-name>/default.nix: This file contains a function that returns a derivation for the package.
To run the packages defined here, you can use the following command:
1

nix run <local or remote path to flake>#<package-name>

NixOS and Home Manager Modules

modules/ (optional): This directory is used for managing one or more computer systems with NixOS or configuring user environments, such as dotfiles. It provides a central location for your Nix modules. When I mention dotfiles, you might think of configuration files for various software, and you’re not far off. However, with Snowfall, we can create reusable modules that can be imported into other configurations. For example, you could define how an Apache Kafka server should be configured when deployed to a system or specify which plugins should automatically be available in Firefox when setting up a home environment. We’ll dive deeper into this with later Posts.
- <platform>/<module-name>/default.nix: Platform-specific modules, such as for nixos or darwin.

Overlays

overlays/ (optional): Overlays are a powerful feature in Nix that allow you to customize or extend the pkgs namespace from your chosen nixpkgs version. For instance, you can use an overlay to select the latest version of Firefox from the unstable branch or to replace the default Neovim with your customized version whenever Neovim is added. Think of overlays as a way to “overlay” additional packages or configurations onto the existing package set. You can use them to override existing packages or introduce new ones.
- <overlay-name>/default.nix: This file contains a function to modify the set of packages (pkgs).
For example, here’s what nix-tutor/default.nix might look like, providing pkgs.nix_tutor as an installable package elsewhere in the Flake:
1 2 3 4 5

{ channels, nix-tutor, nixpkgs, ... }: final: prev: { nix_tutor = nix-tutor.packages.${prev.system}.menu; }

System Configurations

systems/ (optional): This directory is for configurations of your NixOS systems, virtual machines, or AMIs for cloud platforms like Azure or AWS. The system configurations here generally don’t contain extensive logic; instead, they primarily enable modules defined in the modules/ directory. This setup allows for highly standardized systems or VMs that can be reconfigured and updated dynamically, ensuring consistency across deployments.

For instance, in my personal dotfiles repo, I’ve set up GitLab CI/CD to automatically build all my systems upon commit and deploy them upon merge. This approach transforms system management, as any system can build another and then deploy the resulting configuration, opening up numerous possibilities!

<architecture>-<format>/<system-name>/default.nix: Configuration files for specific systems (e.g., x86_64-linux, aarch64-darwin).

Here’s an example configuration, where initech includes modules defined in the modules directory:

{
  pkgs,
  config,
  lib,
  ...
}:
with lib;
in {
  imports = [ ./hardware.nix ];

  initech = {
    archetypes.developer = enabled;

    system = {
      boot = enabled;
      passwds = enabled;
    };

    user = {
      name = "gumby";
      fullName = "Matt Camp";
      email = "matt@aicampground.com";
      extraGroups = [ "wheel" ];
    };

    services = {
      openssh = {
        enable = true;
        authorizedKeys = [
          "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGw+o+9F4kz+dYyI2I4WudgKjyFOK+L0QW4LhxkG4sMt
          gitlab-runner@aicampground.com"
          "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKdMWMFyi7Lvjm78KOX3tKZ5bkEZ7bHA56ZKKtTb9wIo
          mcamp@aicampground.com"
        ];
      };
      ntp = enabled;
    };
  };

  system.stateVersion = "23.05";
}

In this configuration, various modules and services are specified, such as SSH keys and NTP services, ensuring a consistent setup across the system.

User Home Configurations

homes/ (optional): This directory is used for home environment configurations, which are similar to system configurations but tailored for individual users rather than entire systems. These configurations can be applied across various operating systems, not just NixOS. For example, you might want to provide standardized yet customizable user environments for everyone in your organization. Each user could have a configuration in this directory, allowing them to enable specific modules with customized options.
<architecture>-<format>/<home-name>/default.nix: Configuration file for individual user home environments.

Here’s an example user configuration file:

{
  lib,
  pkgs,
  config,
  ...
}:
{
  initech = {
    user = {
      enable = true;
      name = "gumby";
      fullName = "Matt Camp";
      email = "matt@aicampground.com";
    };

    cli = {
      zsh = enabled;
      bash = enabled;
      env = enabled;
      home-manager = enabled;
      k9s = enabled;
      broot = enabled;
      ranger = enabled;
      neovim = enabled;
    };

    services = {
      openssh = enabled;
      syncthing = enabled;
    };

    tools = {
      git = enabled;
      direnv = enabled;
      vault = enabled;
    };
  };

  home.stateVersion = "23.05";
}

A user could activate this configuration with the following command:

`1`	`nix run <path to flake>#homeConfigurations.<user-name>@<system-name>.activationPackage`

This setup allows for defining a variety of user-specific settings and applications, which can be easily deployed and managed across different systems.

Development Shells

shells/ (optional): This directory is where you can define various Nix shells. Think of these shells as being similar to Docker containers but with less isolation. When you activate a Nix shell, it makes all the specified programs and environment variables available, allowing users to easily set up a consistent environment across different systems. This is particularly useful for organizations adopting Nix, as it simplifies the onboarding process by providing a pre-configured development environment. No more spending days or weeks setting up; a well-defined shell can get new team members up and running quickly.

However, be cautious about the temptation to include everything your team uses in a single shell. While possible, this can lead to long initial load times and a less efficient setup. A better strategy is to create shells tailored to specific tasks—one for building projects, another for testing, etc. This way, you load only what you need, when you need it, but you still have the option to include everything if that’s what you prefer.

<shell-name>/default.nix: This file contains a function that defines the Nix shell.

Here’s an example of a simple shell:

{ mkShell, pkgs, ... }:
mkShell {
  buildInputs = with pkgs; [
    neovim
    k3d
    podman
    kubernetes
    k9s
  ];

  shellHook = ''
    echo -e "\e[32m+-----------------------------------------------------------+\e[0m"
    echo -e "\e[32m|⮺  Initech: Is it good for the company?                    |\e[0m"
    echo -e "\e[32m+-----------------------------------------------------------+\e[0m"

    # Additional setup can go here
  '';
}

To activate the shell defined here, you can use the following command:

`1`	`nix develop <local or remote path to flake>#<shell-name>`

This setup ensures a reproducible and efficient development environment tailored to your team’s needs.

Templates

templates/ (optional): This directory is used for storing directories of templated files that you want to reuse. These templates are basic and don’t support automatic modification but can be a helpful starting point for writing new modules or Flakes.
- <template-name>/: Files and folders placed here will be created wherever the template is deployed.

To deploy a template, use the following command in the directory where you want the templated files to be generated:

`1`	`nix flake init --template <local or remote path to flake>#<template-name>`

This command will create the template’s files and folders at the specified location, making it easy to set up new projects with a predefined structure.

Creating a Default Shell Environment

Earlier, I provided a snippet of a basic Nix development shell, which is perfectly sufficient for many needs. However, I’ve had great success using a specialized development shell by Numtide. This shell uses TOML files to define the entire environment, which is especially appealing to those who are still hesitant about adopting Nix. The TOML configuration is straightforward, and you can easily extend it with pure Nix code for more advanced functionality. In this section, I’ll show you how to set up a simple default Nix development shell using the Numtide dev shell.

Update the `flake.nix`

Add the Numtide Devshell Flake to the `inputs`

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
  unstable.url = "github:nixos/nixpkgs?ref=nixos-unstable";

  snowfall-lib = {
    url = "github:snowfallorg/lib";
    inputs.nixpkgs.follows = "nixpkgs";
  };

  devshell.url = "github:numtide/devshell"; # <-- We added this right here
};

Add the Numtide Devshell to the `mkFlake` Function’s `overlays` Argument

Using the overlays argument in mkFlake is a bit different from adding overlays to the /overlays directory. This approach is good for quickly adding predefined functionality, like devshell.overlays.default, which brings in default features from the devshell Flake with minimal fuss. On the other hand, using the /overlays directory is more about allowing you to tweak how packages from nixpkgs are modified or added.

outputs = inputs:
  inputs.snowfall-lib.mkFlake {
    inherit inputs;
    src = ./.;
    snowfall = {
      root = ./.;
      namespace = "initech";
      meta = {
        name = "initech";
        title = "Initech Demo Codebase";
      };
    };
    overlays = with inputs; [
      devshell.overlays.default
    ];
  };

Make a Devshell

Now that you’ve added the overlay, the next step is to create the devshell. In the /shells folder, create a new folder named default and place a default.nix file inside it.

{ pkgs,
  config,
  lib,
  system,
  ...
}:
pkgs.devshell.mkShell {
  imports = [ (pkgs.devshell.importTOML ./devshell.toml) ];

  name = "initech";
  motd = ''
         {214}⮺  Is it good for the company? ⮺{reset}
         $(type -p menu &>/dev/null && menu)
       '';

  commands = [
    {
      name = "nix-tutor";
      command = "${pkgs.nix_tutor}/bin/tutor-menu";
    }
  ];
}

Next, add a devshell.toml file to the same directory. Note: You can name the file anything you like; just remember to update default.nix with the correct path and filename. The simple toml file below demonstrates adding Hashicorp’s Vault to an environment and a custom shell alias called git-root, which returns the path to the root of a Git project.

[[commands]]
package = "vault"

[[commands]]
name = "git-root"
help = "Print the root directory of the Git project."
category = "shell tools"
command = """
#!/bin/sh

# Function to get Git root directory
get_git_root() {
    git rev-parse --show-toplevel
}

# Print the Git root directory
echo $(get_git_root)
"""

This setup not only adds the Vault package to your environment but also defines a custom command to easily find the root of your Git project, showcasing the flexibility and power of using a devshell with Nix.

One last step: you may have noticed I added a command nix-tutor in the default.nix, which comes from a package of the same name. This is a small project I started to provide simple Nix lessons, mainly included here for illustrative purposes. You won’t find nix-tutor on Nixpkgs, as it’s not included there. To use it, you’ll need to create an overlay.

Go ahead and create a folder in the /overlays directory and name it nix-tutor (feel free to use any name that makes sense to you). Inside that folder, create a default.nix file and add the following overlay:

{ channels, nix-tutor, nixpkgs, ... }:

final: prev: {
  nix_tutor = nix-tutor.packages.${prev.system}.menu;
}

Also, ensure nix-tutor is included in your Flake’s inputs:

`1`	`nix-tutor.url = "gitlab:usmcamp0811/nix-tutor";`

And because we are using Vault, which has a “non-free” license, we need to enable it in the mkFlake function like this:

inputs.snowfall-lib.mkFlake {
  inherit inputs;
  src = ./.;
  snowfall = {
    root = ./.;
    namespace = "initech";
    meta = {
      name = "initech";
      title = "Initech Demo Codebase";
    };
  };
  channels-config.allowUnfree = true; # <- Add this to allow unfree packages like Vault
  overlays = with inputs; [ devshell.overlays.default ];
};

If you tried running this and encountered an error, you might have forgotten to add the necessary files to Git. Make sure to run:

1
2

git add shells/default/default.nix
git add shells/default/devshell.toml

Once you’ve done that, you can activate the shell by simply running:

nix develop

# The above is the same as this because the shell is named `default`.
# If you named the folder anything else, you would need to use that name here.
nix develop .#default

One more thing that might not be clear is that you don’t have to clone this repository down in order to activate the devshell.

`1`	`nix develop gitlab.com:initech-project/main-codebase`

Conclusion

In this post, we’ve taken significant steps toward integrating Nix into our codebase, transforming our initial Git project into a Nix Flake with the assistance of Snowfall Lib. We set up a Nix devshell configured with a straightforward TOML file—an approach our team is already comfortable with—and demonstrated how to add overlays to incorporate packages from other Flakes. These initial steps lay a solid foundation for creating reproducible and consistent development environments, significantly streamlining our workflows. In upcoming posts, we’ll explore how we can leverage Nix to fully manage the development, testing, packaging, and deployment processes for the Initech repo. With these tools, we’re well on our way to a more efficient and reliable development pipeline. The changes made to the Initech repo can be seen in this MR. Stay tuned for more insights and practical applications as we continue this journey! Feel free to comment if you have questions or if anything needs more explanation.

Nix in the Wild: Exploring the Power of Nix for Organizational Codebases

Wed, 31 Jul 2024 00:00:00 +0000

Nix in the Wild: Exploring the Power of Nix for Organizational Codebases

Welcome to the first post in an open-ended series I’m calling “Nix in the Wild,” where we will explore how Nix can revolutionize project management in your organization. This series is tailored for DevOps engineers, software developers, and IT managers looking to enhance automation and consistency in their workflows. I will demonstrate how to transition a typical codebase to use Nix and codify the structure of our projects to provide many assurances about them. We will delve into various ideas and concepts related to using Nix in an organizational context. Specifically, I aim to provide real-world examples of how to replace tools like Cookiecutter, Docker and Ansible with Nix. I have created a demo repository that I will use to illustrate these concepts.

Why Nix?

Why do I need something new? I already use templates to generate new projects and have Docker to help deploy my applications to Kubernetes. These are valid questions. However, as the number of projects scales, the problems grow exponentially. It becomes increasingly challenging to keep projects created with older versions of templates in sync with current best practices. For example, I created the Initech main codebase repository using a Cookiecutter template that I made three years ago to standardize new Python projects with best practices like Poetry and avoiding latest tags in Dockerfile. However, when attempting to create projects for the demo repository using this template, the Docker images failed to build. This experience highlights the need for Nix in our workflow. Once templates are instantiated, they become static, necessitating manual updates for each instance.

Note: This is why some things in the demo repo might not build or work as expected. I didn’t spend much time fixing them right now.

Nix offers several advantages, such as automatically generating a software bill of materials for every package, project, or system you create. This is a feature you essentially get for free with Nix, and using a simple tool like sbomnix can enhance your projects transparency and security. Additionally, onboarding new team members becomes significantly faster. Instead of spending a week reading through READMEs to configure their development environment, new hires can use Nix dev shells. They simply clone the project and run nix develop, instantly accessing the exact same environment as the rest of the team, streamlining setup.

Moreover, Nix can drastically simplify your CI/CD pipelines. It ensures that testing environments are identical to deployment environments by hashing all inputs and preventing internet access during the build and installation phases. This guarantees that the installed packages are consistent, reducing time spent troubleshooting discrepancies.

Furthermore, Nix’s purely functional package management system allows for precise definition and versioning of project dependencies and environment configurations, ensuring consistent and repeatable builds across different systems. In simpler terms, Nix provides a way to describe and manage the infrastructure surrounding your project, allowing for centralized updates and eliminating the drift between old and new projects. This makes it easier to maintain best practices and ensures reliable deployments, significantly reducing time spent troubleshooting and aligning project environments.

By using Nix, you not only streamline your setup processes but also ensure reliable deployments, significantly cutting down on time spent resolving environment-related issues.

Overview of the Series

In this series, I will guide you through the following steps:

Converting the Demo Repository: Transform the demo repository into a fully configured Nix Flake.
Standardizing Project Creation: Demonstrate how Nix library functions can standardize the creation of new projects, ensuring they adhere to consistent configurations.
Using Nix for Development: Explore how Nix can be utilized not just for packaging projects, but also to support and streamline the development process.
Design Decisions and Lessons Learned: Share insights from the design decisions made during the transition and the lessons learned along the way.
Integrating Nix with Kubernetes: Present ideas on how Nix can be integrated into your Kubernetes workflows to enhance deployment and management.

These ideas are just the beginning and are not complete or comprehensive.

Setting Up Nix

Before we go any further, let’s get Nix installed and set up. There are several ways to install Nix, but the most reliable method is using the Determinate Systems installer. This installer ensures a smooth and consistent installation process.

For most cases, the following command should result in Nix being installed:

`1`	`curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix \| sh -s -- install`

After running this command, follow the on-screen instructions to complete the installation. This script will handle all the necessary steps to set up Nix on your system.

Verifying the Installation

Once the installation is complete, you can verify that Nix is installed correctly by running:

`1`	`nix --version`

You should see the version number of Nix displayed, confirming that the installation was successful.

Conclusion

In this post, we introduced the foundational concepts of using Nix to standardize and streamline project management within an organization. We explored why Nix is essential for overcoming the limitations of traditional templates and discussed its benefits in terms of reproducibility, simplicity, and reliability. By following this series, you will learn how to convert your projects into fully configured Nix Flakes, standardize project creation, and integrate Nix into your development workflows.

Stay tuned for the next post, where we will delve into transforming the demo repository into a fully configured Nix Flake using Snowfall Lib. In the meantime, I encourage you to explore my other post on enhancing your Nix skills, LevelUp Your Nix. For a deeper understanding, you might also find it insightful to read the PhD thesis by Eelco Dolstra, the creator of Nix, which lays the foundational concepts that have shaped this tool. Don’t forget to subscribe or follow the blog for updates, and dive into the demo repository to begin your hands-on journey with Nix. I welcome your thoughts and feedback in the comments below.

Thank you for joining me on this exploration of Nix in the wild. Together, we can simplify and enhance our development environments, ensuring consistency and reliability across all projects.

Level Up Your Nix

Thu, 13 Jun 2024 00:00:00 +0000

LevelUp Your Nix

Installing Nix

`1`	`sh <(curl -L https://nixos.org/nix/install) --daemon`

Enable Flakes

Add the following to ~/.config/nix/nix.conf or /etc/nix/nix.conf:

`1`	`experimental-features = nix-command flakes`

Nix Templates

You don’t have to start from zero, you can start with a template.

1
2
3

mkdir project-dir
cd project-dir
nix flake init --template gitlab:usmcamp0811/dotfiles#shell-container

Important Files

flake.nix: The main file for your Nix Flake.
flake.lock: The lock file that tells Nix what commits/dependencies to use for each of your inputs.
.direnv: An optional file that allows you to automatically switch to your Shell when you enter the directory; requires direnv be installed.
.gitignore: Every Flake ~~should~~ needs to be a git repository; so we might want to have a .gitignore.

NOTE: Nix can only see files that have been added to the git repo.

Parts of a `flake.nix`

There are really only two parts to a flake.nix.

`inputs`

This section contains other Flakes you want to use or have available in your Flake. Each is assigned a local name that can be referenced in the Flake.

All three of the following are the same, just different styles of Nix code.

inputs = {
  the-flake-name = {
    url = "gitlab:owner/repo/branch";
  };
};

`1`	`inputs.the-flake-name.url = "gitlab:owner/repo/branch";`

1
2
3

inputs = {
  the-flake-name.url = "gitlab:owner/repo/branch";
};

Note: You can’t mix styles if you are nesting things. The follwing is not valid.

inputs.flakeA.url = "gitlab:owner/repoA/branch";
inputs = {
  flakeB.url = "gitlab:owner/repoB";
};

The correct way would be to do:

inputs = {
  flakeA.url = "gitlab:owner/repoA/branch";
  flakeB.url = "gitlab:owner/repoB";
};

1
2

inputs.flakeA.url = "gitlab:owner/repoA/branch";
inputs.flakeB.url = "gitlab:owner/repoB";

`outputs`

This is the section the as the name implies is the output of your Flake. For the purpose of this tutorial session lets break the outputs section into two parts.

`let`… `in` block

This section is where you can create Nix variables that are the outputs of Nix functions. The functions can do things like create packages or create shells. General programming concepts can apply here, after all it is a programming language.

`[` … `](` … `)` block

This section is part of the flake.nix that is a little more strucutred. There are some standardized outputs that most all Flakes should have, such as packages or devShells.

Make an Executable Shell Script

A simple example of creating an executable shell script follows. It is a simple script that allows for running the Julia package Pluto.jl from the command line without having to launch the Julia REPL. It gets saved as a Nix variable pluto so we can use it elsewhere in our Flake. Below we also define the julia environment that will have the Pluto and PythonCall packages included. We call that Julia environment julia-env and notice how we used it in the pluto shell script. Finally notice that Nix lazily evaluates all of its code, so the order of defining things generally does not matter.


 pluto = pkgs.writeShellScriptBin "pluto" ''
   #!/usr/bin/env bash
   HOST="0.0.0.0" # Default host
   PORT=1234      # Default port

   # Parse command-line arguments for --host and --port
   while [[ "$#" -gt 0 ]]; do
       case $1 in
           --host) HOST="$2"; shift ;;
           --port) PORT="$2"; shift ;;
           *) echo "Unknown parameter passed: $1"; exit 1 ;;
       esac
       shift
   done

   ${julia-env}/bin/julia -e "using Pluto; Pluto.run(host=\"$HOST\", port=$PORT)"
 '';

 julia-env = pkgs.julia.withPackages [ "Pluto" "PythonCall"];

Making a Shell Environment

The following should generally go in the let in block of the outputs section of your flake or in something that gets imported into it. It is a function call that returns a buildEnv that we call shell-env. This isn’t 100% necessary that we do it seperate like we are, but it will allow us to define our environment once, and use it in both a devShell and a OCI compliant container. The function takes a couple of named arguments, the first being name which we just give it a descriptive name. The second argument is paths which is effectively a list of packages to include. For our example we include julia-env which we defined above.

 shell-env = pkgs.buildEnv rec {
   name = "shell-env";
   paths = [
       julia-env
     ];
 };

Below is the actual definition of our shell. There are two arguments (that we have defined here) to pass into the mkShell function, buildInputs and shellHook. The buildInputs is the packages you want to have in your shell environment. Normally you could just place your packages you want inside the list, but because we don’t want to repeat our selves we broke out the above buildEnv and just use that in the buildInput section.

The shellHook can be thought of as your shell’s entrypoint script. It will execute when you enter your shell everytime. For our example we are just echoing some text into the figlet program.

 shell = pkgs.mkShell {
   buildInputs = [ (shell-env) ];
   shellHook = ''
     echo "Example Shell Container with Pluto.jl" | ${pkgs.figlet}/bin/figlet
   '';
 };

Making an OCI Image

You spent all that time getting your environment just right to be able to run your application and now it needs to be containerized so it can run in Kubernetes somewhere. In the traditional Docker workflow you would have to create a Dockerfile and spend a lot of time making sure you included all the dependencies of your application, and their dependencies…and you would have to make sure that the version of the dependency in your base image’s package manager was the correct version (looking at you Debian and Redhat)… several hours later you finally have a Docker image.

With Nix and this way of making your development environment all you have to do to build a container image is the following:

shell-img = pkgs.dockerTools.buildNixShellImage {
  name = "shell-container" ;
  tag = "latest";
  drv = shell;
  command = ''${pluto}/bin/pluto --port ${PORT:-1234}'';
};

This is just a single function call that we assign to the variable shell-img. The function takes four arguments, a name, atag, a drv, and a command which is akin to an entrypoint.

Take note of the drv argument. We are passing shell which is our shell derivation. We also provide a command that is our pluto script we wrote above. So what this will do is create a container image that the only things that exist in it are the things we included in our shell and their dependencies. The entrypoint for the container will be our pluto script.

The Outputs

All the above was in the let … in section of the outputs of our Flake, but now we need to actually export those things that we want to make public by defining some common Flake output variables.

let
# ...
in
{
  devShells.default = shell;
  packages.pluto = pluto;
  packages.container = shell-img;
}

NOTE: You can define as many shells and packages as it makes sense for your flake.

Using the Flake

Flakes don’t necessarily get installed. You can use any flake directly from the remote git repository that it resides or from within the local repository on your computer.

If this flake was in our current directory and it also resided on Gitlab (because GitHub is the devil!) then we could get a shell in our environment we defined either of these two ways.

# local and in the root of the repo
nix develop .

# remote from gitlab
nix develop gitlab:your-username/this-repo#default

You can build the container image and load it into Docker like this:

# local
nix build .#container
docker load -i ./result

# remote
nix build gitlab:your-username/this-repo#container
docker load -i ./result

To run our Pluto program we can do any of the following:

# running the loaded image
docker run -it --rm -p 8888:1234 shell-container

# or why even go through that trouble just run pluto directly
nix run gitlab:your-username/this-repo#pluto -- --host 127.0.0.1 --port 8888

HashiCorp Vault with Database Engine on NixOS

Sun, 15 Oct 2023 00:00:00 +0000

HashiCorp Vault with Database Engine on NixOS: A Quick Guide

This guide is compatible with Vault 1.8+ and NixOS 21.05+, and will walk you through setting up HashiCorp Vault’s Database Secrets Engine on NixOS to manage PostgreSQL database passwords.

Pre-requisites

Vault installed and running
PostgreSQL installed and running
Basic understanding of Vault & NixOS
Basic-to-Advanced understanding of databases

Step 0: Initialize PostgreSQL Database on NixOS

Add the following configuration to your configuration.nix to create an initial PostgreSQL database and user. Read this to learn more about PostgreSQL authentication.

{ pkgs, ... }:
{
    networking.firewall.allowedTCPPorts = [ 5432 ];  # Open PostgreSQL port
    services.postgresql = {
      enable = true;
      package = pkgs.postgresql_13;
      enableTCPIP = true;
      authentication = pkgs.lib.mkOverride 10 ''
        # Allow only local connections for the root user
        local all postgres peer
        # Require password for Vault-generated users over the network
        host  all  all  10.8.0.1/24  md5
        # Deny other remote connections
        host  all  all  0.0.0.0/0  reject
        host  all  all  ::0/0  reject
      '';
      initialScript = pkgs.writeText "postgresql-init.sql" ''
        CREATE DATABASE mydatabase;
        CREATE USER postgres WITH PASSWORD 'postgrespassword';
        GRANT ALL PRIVILEGES ON DATABASE mydatabase TO postgres;
      '';
    };
}

Run nixos-rebuild switch to apply the changes.

Step 1: Enable the Database Engine in Vault

Enable the Vault Database Secrets Engine at the path campground-dbs.

`1`	`vault secrets enable -path=campground-dbs database`

Step 2: Configure PostgreSQL Connection

Next, set up the database connection in Vault. Use a consistent name like my-postgresql-database.

export DB_HOST=mattis
export DB_PORT=5432
export DB_NAME=mydatabase
export ROOT_DB_USER=postgres
export ROOT_DB_PASS=postgrespassword
vault write campground-dbs/config/my-postgresql-database \
    plugin_name=postgresql-database-plugin \
    allowed_roles="*" \
    connection_url="postgresql://{{username}}:{{password}}@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
    username="$ROOT_DB_USER" \
    password="$ROOT_DB_PASS"

Step 3: Create a Role for Credential Generation

Here, db_name should match the Vault database connection name (my-postgresql-database), not the PostgreSQL database name (mydatabase).

vault write campground-dbs/roles/mydb-app \
    db_name=my-postgresql-database \
    creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
    default_ttl="1h" \
    max_ttl="24h"

Step 4: Generate Credentials

Generate a new set of credentials based on the mydb-app role.

`1`	`vault read campground-dbs/creds/mydb-app`

Additional DB Types

Vault also supports other databases like MySQL, MongoDB, etc. The setup is similar; you just have to change the plugin name and connection parameters.

Automated Testing (w/ Gitlab CI/CD & Python)

Thu, 09 Jul 2020 00:00:00 +0000

Automated Testing

These notes will cover how to start a brand new Python project from scratch, initialize a Git repository inside of it, and how to configure the repository to automatically test all your code every time you push to Gitlab. This will be assumed you have some familiarity with the Python programming language, and Git version control system. The tutorial will be broken up into two parts, the first covering how to configure a new project in Python, complete with unit tests, and a second part covering how to make Gitlab automatically run your test scripts every time a change is pushed to your remote repository.

NOTE: For brevity this tutorial is only covering how to do testing in Python, but much of the Gitlab Runner stuff is language agnostic and can be easily applied to your language of choice

Requirements

Gitlab Account
Git
Python >=3.6
- poetry
- pytest
- pytest-cov
- snapshottest

Creating a New Project

We are going to use Poetry to create a new Python Project. I chose Poetry because it does a number of things to make dependecy management in Python much simpiler. It is still a work in progress and some aspects of it are slow but overall it provides a very low barrier of entry for adhearing to some best practices, such as virtual environments, project structuring, depedency tracking, and unit tests.

The following will be done from a Bash terminal on a machine running Linux. You will need to make changes to it for your specific OS. If you are running Windows I HIGHLY!! HIGHLY!! Recommend you at least install and setup Windows Sub-system for Linux (WSL)… or just switch to Linux :-)

# in a directory you store all your different code projects
poetry new automatic_testing
cd automatic_testing
ls -lah

Notice that poetry will create a number of directories and some files. This folder structure is generally accepted to be a best practice in Python. More information on how to use Poetry with an existing code base can be found on the Poetry website.

~/code-home/automatic_testing
├──automatic_testing
│  └──__init__.py
├──pyproject.toml
├──README.rst
└──tests
   ├──__init__.py
   └──test_automatic_testing.py

Init Git Repository

Once our project is created we can go ahead and initialize our Git repository. I suggest adding a .gitignore starter files can be found here.

1
2

git init
git add .

Add Python Code

Now that we have created the scafolding for our Python project and initilized the Git repo lets add some code. The following code is nothing special, just something I threw together quickly in order to be an example for testing. Either create a file containing the code below or feel free to use your own code.

# located at ~/code-home/automatic_testing/automatic_testing/hello_world.py
import os
import datetime
import maya

def hello(user: str="World"):
    print(f"Hello {user}!")

def add(a: float, b: float) -> float:
    c = a + b
    return c

def mult(a: float, b: float) -> float:
    c = a * b
    return c

def div(a: float, b: float) -> float:
    c = a / b
    return c

def sub(a: float, b: float) -> float:
    c = a - b
    return c

def age(dob: str) -> int:
    dob = maya.when(dob)
    age = maya.MayaInterval(start=dob, end=maya.now())
    print("You were born ", maya.humanize.naturaltime(age.duration))
    return int(age.duration.split(" ")[0])

if __name__ == "__main__":
    import argparse

    parser = argparse.ArgumentParser("Simple program to test Gitlab CI/CD")
    parser.add_argument('-u', '--user-name', action='append', help='This is the name that will be printed in the greeting')
    parser.add_argument('-a', '--A', type=float, help="A value to have something done to.")
    parser.add_argument('-b', '--B', type=float, help="B value to do something to A.")
    parser.add_argument('-f', '--function', dest='function', choices=['add', 'mult', 'div', 'sub'], help="The name of the function to run")
    parser.add_argument('-dob', dest='dob', type=str, help="Human formated date of birth")
    args = parser.parse_args()

    if args.user_name:
        hello(user=args.user_name[0])
    else:
        hello()

    if args.function:
        funcs = dict(add=add, mult=mult, div=div, sub=sub)
        print("Your answer is: ", funcs[args.function](a=args.A, b=args.B))

    if args.dob:
       age(args.dob)

Add Test Code

Testing is critical to having good dependable code. Test driven design principles say that we should never write code unless we are writing it to pass a test case. Realistically this might not always happen, but either way we need to have some tests setup so we know if our code is doing what we say it should be doing. Copy the following code into your project or write your own tests. A good strategy for organizing your tests is to create one test file per normal file. I generally keep all my tests stored in a ./tests/ directory and follow the pattern of <real_code>.py and test_<real_code>.py.

Pytest is my prefered method for testing in Python, but there are other ways and you don’t even have to use a package, but it can make things simiplier. Again for brevity sake this tutorial will not go into great detail on all the different features of pytest but rather just showcase some practical examples.

Key Points

Only have to do import pytest in your test file.
To test your code make an assertion that your code does what you say it should, and thats it.
Snapshot testing is good for tracking how changes in code effect your data… just do import snapshottest.
To run your tests using Poetry you can do poetry run pytest and it will run the tests and provide you with the results

Options Reference

-x stops on first failure
-v -vv -vvv various levels of verbousness
-k "<part of test name>" run a specific test(s) aka Key word expression
-cov=<module to test> <tests> get coverage report

# located at ~/code-home/automatic_testing/tests/test_hello_world.py
import pytest
import snapshottest
from automatic_testing.hello_world import add, sub, mult, div, hello

def test_add(snapshot):
    t1 = dict(a=1, b=1, c=add(1,1))
    snapshot.assert_match(t1)

    t2 = dict(a=8, b=34, c=add(8,34))
    snapshot.assert_match(t2)

    assert add(1, 1) != 3

    assert add(40, 2) == 42

def test_mult(snapshot):

    t1 = dict(a=1, b=1, c=mult(1,1))
    snapshot.assert_match(t1)

    t2 = dict(a=8, b=34, c=mult(8,34))
    snapshot.assert_match(t2)

    assert mult(12, 1) != 13

    assert mult(5, 5) == [25](25)

PyProject File

Just to make sure all dependecies are met for this project here is the pyproject.toml file I was using.

[tool.poetry]
name = "automatic_testing"
version = "0.1.0"
description = ""
authors = ["Matthew Camp <usmcamp0811@gmail.com>"]

[tool.poetry.dependencies]
python = "^3.6"
maya = "^0.6.1"

[tool.poetry.dev-dependencies]
pytest = "^5.2"
snapshottest = "^0.5.1"
pytest-cov = "^2.10.0"
pytest-flake8 = "^1.0.6"
pytest-bandit = "^0.5.2"
isort = "^5.0.4"
black = "^19.10b0"
pytest-black = "^0.3.10"
pytest-logger = "^0.5.1"
loguru = "^0.5.1"
coverage-badge = "^1.0.1"

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

Create Gitlab Runner Script

Gitlab will start a “Runner” whenever a repository has a .gitlab-ci.yml file present. You can think of the yaml file as kind of a cross between a Dockerfile and a docker-compose file (If you don’t know what either of those are then just think of it as a script that will create a virtual environment for your project). The file lets you instantiate a single docker container or a series of them to run your code. The computer resources used to run the container are either shared resources belonging to Gitlab or you can create a Local Runner on your own hardware. Creating a Local Runner is outside the scope of this tutorial but this method would allow for test containers to have access to large or senstive files.

The Parts of the YAML File

Image: The Docker Image you want Gitlab to run things on.
Stages: List out the names of the stages you want Gitlab to run for you (ie. Build, Test, Deploy).
Before Script: Any scripting that needs to be done to prep your environment ahead of time
Stage Section:
- Build Definition: All the steps that need to be done to build your project. Not so important for Python… more relevant for a compiled language
- Test Definition: The steps required to run Pytest or any other testing your project requires.
- Deploy Definition: You got here so your code is probably production ready..so lets push it to a Repository or what ever place is should go in order to be put into production.

Minimal Example Yaml File

stages:
  - test

test:
  image: python:3.8
  stage: test
  script:
    - pip install poetry pip --upgrade
    - poetry install
    - poetry run pytest --cov=automatic_testing tests/
    - poetry run coverage-badge
  coverage: "/TOTAL.+ ([0-9]{1,3}%)/"

More Advanced Example NOTE: This is still a work in progress but it does work as it was adapted from an issue on the Poetry GitHub

variables:
  PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip"

cache:
  key: "${CI_JOB_NAME}"
  paths:
    - .cache/pip
    - .venv

stages:
  - quality
  - tests

.install-deps-template: &install-deps
  before_script:
    - pip install poetry
    - poetry --version
    - poetry config virtualenvs.in-project true
    - poetry install -vv

.quality-template: &quality
  <<: *install-deps
  image: python:3.6
  stage: quality

.test-template: &test
  <<: *install-deps
  stage: tests
  coverage: "/TOTAL.+ ([0-9]{1,3}%)/"
  script:
    - poetry run pytest --cov=automatic_testing tests/
    - poetry run coverage-badge

  artifacts:
    paths:
      - tests/logs

    when: always
    expire_in: 1 week

# Quality jobs ----------------------

check-bandit:
  <<: *quality
  script: poetry run bandit .

check-black:
  <<: *quality
  script: poetry run black .

# check-flake8:
#   <<: *quality
#   script: poetry run flake8 ./automatic_testing

check-isort:
  <<: *quality
  script: poetry run isort .

# Tests jobs ------------------------

python3.6:
  <<: *test
  image: python:3.6

python3.7:
  <<: *test
  image: python:3.7

python3.8:
  <<: *test
  image: python:3.8

Build a Docker Image Example NOTE: This is also still under development but the basics are here

image: docker:19.03.1-dind

stages:
  - build_image
  - test

build_image:
  image: docker:latest
  stage: build_image
  script:
    # IMPORTANT!! For this to work you MUST! run `dockerd`
    - dockerd &
    - sleep 5
    - echo "Building"
    - docker build -t ci-cd-example .
    - docker login -u $CI_REGISTERY_USER -p $CI_REGISTERY_PASSWORD $CI_REGISTERY
    - docker push ci-cd-example
    - mkdir build
    - echo "Built example image" > build/example.txt
  artifacts:
    paths:
      - build/

test:
  stage: test
  script:
    - echo "Testing"
    - test -f "build/example.txt"

Mon, 01 Jan 0001 00:00:00 +0000

RMF Compliance on NixOS: A Modern Framework for Secure, Auditable Systems

Introduction

Achieving compliance with the Risk Management Framework (RMF) has traditionally been a manual and cumbersome process. System integrators and software vendors must work in lockstep to ensure that supply chain integrity, auditing, and control enforcement align with NIST 800-53 requirements. This is often hard to scale, difficult to automate, and resistant to modular reuse.

I present a new framework designed idea for Nix/NixOS that brings modern software engineering practices—declarative configuration, reproducibility, and immutability—to the RMF compliance process. This model provides a clean division of responsibilities between software vendors and government integrators.

Goals

Modular Compliance: Shift RMF enforcement into structured metadata and modular NixOS components
Automation: Enable automated control checks, waivers, and audit logging
Reusability: Support composable and reusable compliance modules across projects

Core Concepts

The framework defines two primary roles:

Vendors

Use wrapWithRMF to wrap their software packages with RMF metadata and optional install logic. This allows:

Declaring which RMF controls are “met” or “waived”
Attaching justifications for waived controls
Including install modules to automatically configure services
Exposing configuration options (e.g., port numbers) as moduleOptions

Integrators

Use mkRmfModuleFromPackage to consume wrapped packages and:

Enable/disable the package in system configs
Selectively enforce or waive controls
Provide system-specific overrides for settings

Example Use Case

Vendor Code

wrapWithRMF {
  pkg = myApp;
  rmfMeta = {
    approved = false;
    controls = {
      "AC-17" = {
        status = "met";
        config = { networking.firewall.enable = true; };
        srg = [ "SRG-APP-000516" ];
        cci = [ "CCI-000366" ];
      };
      "CM-2" = {
        status = "waived";
        justification = "Manually configured for dev.";
        config = { nix.settings.warn-dirty = true; };
        srg = [ "SRG-APP-000142" ];
        cci = [ "CCI-000366" ];
      };
    };
    poc = "DevSecOps <sec@aicampground.com>";
    lastReviewed = "2025-08-15";
  };
  installModule = { config, pkgs, lib, ... }: {
    config = {
      systemd.services.myApp = {
        wantedBy = [ "multi-user.target" ];
        serviceConfig.ExecStart = "${myApp}/bin/start";
      };
      environment.systemPackages = [ myApp ];
    };
  };
  moduleOptions = {
    port = lib.mkOption {
      type = lib.types.port;
      default = 8080;
      description = "HTTP port to run the app.";
    };
  };
}

Integrator Code

campground.rmf.example-flask-app = {
  enable = true;
  settings = {
    port = 9001;
  };
  controls = {
    CM-2 = {
      enabled = false;
      justification = [ "dev system" ];
    };
  };
};

Built-in Guarantees

Every control must be marked as met or waived
Every waived control must include a justification
Control configs are enforced only if enabled
Install logic is executed only if the package is enabled

These guarantees ensure that compliance status is declarative and machine-auditable.

Glossary

Term	Description
`rmfMeta`	Metadata declaring RMF control statuses and audit data
`controls`	Per-control compliance information, configuration, and tags
`settings`	Configurable values surfaced by the vendor
`installModule`	Optional vendor logic to configure the application

Future Directions

Add support for STIG profile selection
Auto-generate OSCAL compliance reports
Build CI checks for control status validation
Include SBOM as passthru metadata
Support VM-based penetration testing

Conclusion

This framework brings reproducibility and modularity to RMF compliance on NixOS. By splitting responsibilities and enforcing structure through type-safe Nix code, it enables secure-by-default patterns that can scale across large, multi-team programs. It sets the foundation for integrating security compliance into the software development lifecycle, rather than treating it as a post-hoc audit artifact.

Learn more or contribute at: github.com/usmcamp0811/rmf-nix

Posts on The Campground Blog

Beyond YAML: The Case for Nix as the Common Language of DevSecOps

Beyond YAML: The Case for Nix as the Common Language of DevSecOps

DevSecOps Has Outgrown Basic YAML Configs

Why YAML Falls Short in a DevSecOps World

Nix: A Functional, Declarative Solution for Secure Builds

Reproducibility, Traceability, and Policy Enforcement by Default

One Coherent Pipeline Replacing Many Fragile Pieces

Conclusion: Lead the Next Evolution – Adopt Nix for DevSecOps

Nix in the Wild: Taming Terraform with Nix

What is Terranix?

Addressing Terraform’s Verbosity

Enhancing Reusability

How to Use Terranix

Update flake.nix

Create a Terraform Configuration

Deploying our Cloud Infrastructure with Terranix

Building and Organizing Modules

A Brief Explanation of the NixOS Module System

Creating a Basic Terraform Module

Using Options to Customize Modules

How do I create Options?

Defining Options in a Terraform Module

Using Options to Customize Modules

Integration with the Nix Ecosystem

How the Integration Works:

Key Points:

Understanding Terranix’s Nuances

Important Note:

Breaking Down My Terranix Library Functions

findDefaultNixFiles

mkTerranixDerivation

pushLambdaToAWS

Conclusion

Setting Up Authentik and Netbird with Nix

Netbird & Authentik Setup

Authentik

Configuring Authentik

Netbird

Cloudflare Proxy Considerations

How to stand-up Vault with NixOS

How to stand-up Vault in a New Environment

Step 1. Deploy Barebones Archetype

Step 2. Initialize & Unseal Vault

Step 3. Accessing Vault UI and Configuring Vault

Vault UI

Adding Secrets with the CLI

Adding Policies

Step 4. Creating Approles

Step 5. Configure NixOS to use an Approle

Migrating from file backend to raft

Nix in the Wild: DRYing Out Your Codebase with Reusable Library Functions

DRYing Out Your Codebase with Reusable Library Functions

Managing Complexity: Simplifying Verbose Nix Expressions

Scaling Simplicity: Creating Reusable Functions for Standardized Nix Projects

Breaking Down the mkPythonDerivation Function

Using mkPythonDerivation in our Codebase

Wrapping it up

Nix in the Wild: Packaging Python Projects and Building Containers

Packaging Python Projects and Building Containers with Nix

Why Package Python Projects with Nix?

Setting Up Python Projects as Nix Packages

Adding poetry2nix to our Flake

To Move the Projects or Not to Move Them: That Is the Question

Packaging

Creating the Python Environment

Handling an Edge Case

How to Run the App

Providing a Python Interpreter via passthru

Simplifying Testing

Building Docker Images

Wrapping Up

Nix in the Wild: Nixing Your Codebase

Nix in the Wild: Nixing Your Codebase

Setting Up Nix with Flakes

What Are Flakes?

Why Use a Monorepo?

Setting Up flake.nix

Why Use Snowfall Lib?

Configuring Inputs

Update `flake.nix`

`findDefaultNixFiles`

`mkTerranixDerivation`

`pushLambdaToAWS`

Migrating from `file` backend to `raft`

Breaking Down the `mkPythonDerivation` Function

Using `mkPythonDerivation` in our Codebase

Adding `poetry2nix` to our Flake

Providing a Python Interpreter via `passthru`

Setting Up `flake.nix`

Update the `flake.nix`

Add the Numtide Devshell Flake to the `inputs`

Add the Numtide Devshell to the `mkFlake` Function’s `overlays` Argument

Parts of a `flake.nix`

`inputs`

`outputs`

`let`… `in` block

`[` … `](` … `)` block