MarcoPolo – Partially Functional - Nix

Declarative Dev Environments

2021-05-10T00:00:00+00:00

I don't install development tools globally. I don't have node</code> added to my PATH</code> in my ~/.zshrc</code> file, and running cargo</code> outside a project folder returns "command not found." I wipe my computer on every reboot. With the exception of four folders (/boot</code>, /nix</code>, /home</code>, and /persist</code>), everything gets deleted</a>. And it has worked out great.</p>

Instead of installing development packages globally, I declare them as a dependency in my project's dev environment. They become available as soon as I cd</code> into the project folder. If two projects use the same tool then I only keep one version of that tool on my computer.</p>

I think installing dev tools globally is a bad pattern that leads to nothing but heartache and woe. If you are running sudo apt-get install</code> or brew install</code> prior to building a project, you are doing it wrong. By defining your dev tool dependencies explicitly you allow your projects to easily build on any machine at any point in time. Whether it's on a friends machine today, or a new laptop in 10 years. It even makes CI integration a breeze.</p>

What do I mean by a declarative dev environment?</h2>
I mean a project that has a special file (or files) that define all the
dependencies required to build and run your project. It doesn't necessarily have
to include the actual binaries you will run in the repo, but it should be
reproducible. If you clone my project you should be running the exact
same tools as me.</p>
Just like you have explicit dependencies on libraries you use in your program, a
declarative dev environment lets you define your tooling dependencies (e.g.
which version of Node, Yarn, or your specific cross compiler toolchain).</p>

How I setup my declarative dev environments</h2>
To accomplish this I use Nix</a> with Nix Flakes</a> and direnv</a>. There are three
relevant files: flake.nix</code> which defines the build of the project and the tools
I need for development; flake.lock</code> which is similar in spirit to a yarn.lock</code>
or Cargo.lock</code> file, it locks</em> the exact version of any tool used and
generated automatically the first time you introduce dependencies; and finally a
.envrc</code> file which simply tells direnv to ask Nix what the environment should
be, and sets up the environment when you cd</code> into the folder. Here are some
simple examples:
flake.nix</a>,
.envrc</a>
(flake.lock</code> omitted since it's automatically generated).</p>
As a shortcut for setting up a flake.nix</code> and .envrc</code>, you can use a template
to provide the boilerplate. When I start a new project I'll run nix flake init -t github:marcopolo/templates</code> which copies the files from this
repo</a> and puts them
in your current working directory. Then running direnv allow</code> will setup your
local environment, installing any missing dependencies through Nix as a side
effect.</p>
This blog itself makes use of declarative dev
environments</a>.
Zola is the static site generator I use. When I cd</code> into my blog my environment
is automatically setup with Zola available for previewing the blog.</p>
How Nix works, roughly</h2>
This all works off Nix</a>. Nix is a fantastic package manager and build tool that
provides reproducible versions of packages that don't rely on a specific global
system configuration. Specifically packages installed through Nix don't rely an
a user's /usr/lib</code> or anything outside of /nix/store</code>. You don't even need
glibc installed (as may be the case if you are on Alpine
Linux</a>).</p>
For a deeper dive see How Nix Works</a>.</p>
An example, how to setup a Yarn based JS project.</h2>
To be concrete, let me show an example. If I wanted to start a JS project and
use Yarn</a> as my dependency manager, I would do something
like this: </p>
# 1. Create the project folder
mkdir my-project

# 2. Add the boilerplate files.
nix flake init -t github:marcopolo/templates

# 3. Edit flake.nix file to add yarn and NodeJS.
# With your text editor apply this diff:
# -          buildInputs = [ pkgs.hello ];
# +          buildInputs = [ pkgs.yarn pkgs.nodejs-12_x ];

# 4. Allow direnv to run this environment. This will also fetch yarn with Nix
#    and add it to your path.
direnv allow

# 5. Yarn is now available, proceed as normal. 
yarn init
</code></pre>
You can simplify this further by making a Nix Flake template that already has
Yarn and NodeJS included. </p>
Another example. Setting up a Rust project.</h2>
# 1. Create the project folder
mkdir rust-project

# 2. Add the boilerplate files.
nix flake init -t github:marcopolo/templates#rust

# 3. Cargo and rust is now available, proceed as normal. 
cargo init
cargo run
</code></pre>
Here we used a Rust specific template, so no post template init changes were required.</p>
Dissecting the flake.nix</code> file</h2>
Let's break down the flake.nix</code> file so we can understand what it is we are
declaring.</p>
First off, the file is written in Nix, the programming
language</a>. At a high level you
can read this as JSON but with functions. Like JSON it can only represent
expressions (you can only have one top level JSON object), unlike JSON you can
have functions and variables. </p>
# This is our top level set expression. Equivalent to the top level JSON object.
{
  # These are comments

  # Here we are defining a set. This is equivalent to a JSON object.
  # The key is description, and the value is the string.
  description = "A very basic flake";

  # You can define nested sets by using a `.` between key parts.
  # This is equivalent to the JSON object {inputs: {flake-utils: {url: "github:..."}}}
  inputs.flake-utils.url = "github:numtide/flake-utils";

  # Functions are defined with the syntax of `param: functionBodyExpression`.
  # The param can be destructured if it expects a set, like what we are doing here. 
  # This defines the output of this flake. Our dev environment will make use of
  # the devShell attribute, but you can also define the release build of your
  # package here.
  outputs = { self, nixpkgs, flake-utils }:
    # This is a helper to generate these outputs for each system (x86-linux,
    # arm-linux, macOS, ...)
    flake-utils.lib.eachDefaultSystem (system:
      let
        # The nixpkgs repo has to know which system we are using.
        pkgs = import nixpkgs { system = system; };
      in
      {
        # This is the environment that direnv will use. You can also enter the
        # shell with `nix shell`. The packages in `buildInputs` are what become
        # available to you in your $PATH. As an example this only has the hello
        # package.
        devShell = pkgs.mkShell {
          buildInputs = [ pkgs.hello ];
        };

        # You can also define a package that is built by default when you run
        # `nix build`.  The build command creates a new folder, `result`, that
        # is a symlink to the build output.
        defaultPackage = pkgs.hello;
      });
}

</code></pre>
On Dev Tools and A Dev Setup</h2>
There is a subtle distinction on what constitutes a Dev Tool vs A Dev Setup. I
classify Dev Tools as things that need to be available to build or develop a given
project specifically. Think of gcc</code>, yarn</code>, or cargo</code>. The Dev Setup category
are for things that are useful when developing in general. Vim, Emacs,
ag</a> are some examples.</p>
Dev tools are worth defining explicitly in your project's declarative dev environment (in
a flake.nix</code> file). A Dev Setup is highly personal and not worth defining in the
project's declarative dev environment. But that's not to say your dev setup in not
worth defining at all. In fact, if you are (or when you become) familiar with
Nix, you can extend the same ideas of this post to your user account with Home
Manager</a>. </p>
With Home Manager You can declaratively define which programs you want available
in your dev setup, what Vim plugins you want installed, what ZSH plugins you
want available and much more. It's the core idea of declarative dev environments
taken to the user account level.</p>
Why not Docker?</h2>
Many folks use Docker to get something like this, but while it gets close – and
in some cases functionally equivalent – it has some shortcomings:</p>
For one, a Dockerfile is not reproducible out of the box. It is common to use
apt-get install</code> in a Dockerfile to add packages. This part isn't reproducible
and brings you back to the initial problem I outlined. </p>
Docker is less effecient with storage. It uses layers as the base block of
Docker images rather than packages. This means that it's relatively easy to end
up with many similar docker images (for a more thorough analysis check
out Optimising Docker Layers for Better Caching with
Nix</a>).</p>
Spinning up a container and doing development inside may not leverage your
existing dev setup. For example you may have Vim setup neatly on your machine,
but resort to vi</code> when developing inside a container.  Or worse, you'll 
rebuild your dev setup inside the container, which does nothing more than
add dead weight to the container since it's an addition solely for you and not
really part of the project. Of course there are some workarounds to this issue,
you can bind mount a folder and VS Code supports opening a project inside a
container.  ZMK</a> does this and it has
worked great.</p>
If you are on MacOS, developing inside a container is actually slower. Docker
on Mac relies on running a linux VM in the background and running containers in
that VM. By default that VM is underpowered relative to the host MacOS machine.</p>
There are cases where you actually do only want to run the code in an
x86-linux environment and Docker provides a convenient proxy for this. In these
cases I'd suggest using Nix to generate the Docker images. This way you get the
declarative and reproducible properties from Nix and the convenience from Docker.</p>
As a caveat to all of the above, if you already have a reproducible dev environment
with a Docker container that works for you, please don't throw that all out and
redesign your system from scratch. Keep using it until it stops meeting your
needs and come back to this when it happens. Until then, keep building.</p>
On Nix Flakes</h2>
Nix Flakes is still new and in beta, so it's likely that if you install Nix from
their download page</a> you won't have Nix Flakes
available. If you don't already have Nix installed, you can install a version
with Nix Flakes with the unstable installer</a>,
otherwise read the section on installing flakes</a>.</p>
Closing thoughts</h2>
In modern programming languages we define all our dependencies explicitly and
lock the specific versions used. It's about time we do that for all our tools
too. Let's get rid of the apt-get install</code> and brew install</code> section of READMEs.</p>

Simple Declarative VMs 2021-03-24T00:00:00+00:00 I've been on a hunt to find a simple and declarative way to define VMs. I wanted something like NixOS Containers</a>, but with a stronger security guarantee. I wanted to be able to use a Nix expression to define what the VM should look like, then reference that on my Server's expression and have it all work automatically. I didn't want to manually run any commands. The hunt is over, I finally found it.</p> My Use Case</h2> I want a machine that I can permanently hook up to a WireGuard VPN and treat as if it were in a remote place. At first I did this with a physical machine, but I didn't want to commit the whole machine's compute for a novelty. What I really want is a small VM that is permanently hooked up to a WireGuard VPN. Minimal investment with all the upsides.</p> NixOS QEMU</h2> Nix OS supports building your system in a QEMU runnable environment right out of the box. nixos-rebuild build-vm</code> is a wrapper over nix build github:marcopolo/marcopolo.github.io#nixosConfigurations.small-vm.config.system.build.vm</code>. (Side note, with flakes you can build this exact VM by running that command1</a></sup>). This means NixOS already did the hard work of turning a NixOS configuration into a valid VM that can be launched with QEMU. Not only that, but the VM shares the /nix/store</code> with the host. This results in a really small VM (disk size is 5MB).</p> NixOS does the heavy lifting of converting a configuration into a script that will run a VM, so all I need to do is write a service that manages this process. Enter simple-vms</a>, heavily inspired by vms.nix</a> and nixos-shell</a>. simple-vms</a> is a NixOS module that takes in a reference to the nixosConfigurations.small-vm.config.system.build.vm</code> derivation and the option of whether you want state to be persisted, and defines a Systemd service for the vm (There can be multiple VMs). This really is a simple module, the NixOS service definition is about 10 lines long, and its ExecStart</code> is simply:</p> mkdir -p /var/lib/simple-vms/${name} cd /var/lib/simple-vms/${name} exec ${cfg.vm.out}/bin/run-nixos-vm; </code></pre> With this service we can get and keep our VMs up and running.</p> Stateless VMs</h2> I got a sticker recently that said "You either have one source of truth, of multiple sources of lies." To that end, I wanted to make my VM completely stateless. QEMU lets you mount folders into the VM, so I used that to mount host folders in the VM's /etc/wireguard</code> and /etc/ssh</code> so that the host can provide the VM with WireGuard keys, and the VM can persist it's SSH host keys.</p> That's all the VM really needs. Every time my VM shuts down I delete the drive. And just to be safe, I try deleting any drive on boot too.</p> If you're running a service on the VM, you'll likely want to persist that service's state files too in a similar way.</p> Fin</h2> That's it. Just a small post for a neat little trick. If you set this up let me know! I'm interested in hearing your use case.</p> Footnotes</h3> ^{1</sup> User/pass = root/root. Exit qemu with C-a x.</p> </div>} Backups made simple 2021-03-07T00:00:00+00:00 I've made a backup system I can be proud of, and I'd like to share it with you today. It follows a philosophy I've been fleshing out called The Functional Infra</em>. Concretely it aims to:</p> Be pure. An output should only be a function of its inputs.</li> Be declarative and reproducible. A by product of being pure.</li> Support rollbacks. Also a by product of being pure.</li> Surface actionable errors. The corollary being it should be easy to understand and observe what is happening.</li> </ul> At a high level, the backup system works like so:</p> ZFS creates automatic snapshots every so often.</li> Those snapshots are replicated to an EBS-backed EC2 instance that is only alive while backup replication is happening. Taking advantage of ZFS' incremental snapshot to make replication generally quite fast.</li> The EBS drive itself stays around after the instance is terminated. This drive is a Cold HDD (sc1) which costs about $0.015 gb/month.</li> </ol> ZFS</h2> To be honest I haven't used ZFS all that much, but that's kind of my point. I, as a non-expert in ZFS, have been able to get a lot out of it just by following the straightforward documentation. It seems like the API is well thought out and the semantics are reasonable. For example, a consistent snapshot is as easy as doing zfs snapshot tank/home/marco@friday</code>.</p> Automatic snapshots</h3> On NixOS setting up automatic snapshots is a breeze, just add the following to your NixOS Configuration:</p> { services.zfs.autoSnapshot.enable = true; } </code></pre> and setting the com.sun:auto-snapshot</code> option on the filesystem. E.g.: zfs set com.sun:auto-snapshot=true <pool>/<fs></code>. Note that this can also be done on creation of the filesystem: zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true tank/home</code>.</p> With that enabled, ZFS will keep a snapshot for the latest 4 15-minute, 24 hourly, 7 daily, 4 weekly and 12 monthly snapshots.</p> On Demand EC2 Instance for Backups</h3> Now that we've demonstrated how to setup snapshotting, we need to tackle the problem of replicating those snapshots somewhere so we can have real backups. For that I use one of my favorite little tools: lazyssh</a>. Its humble description betrays little information at its true usefulness. The description is simply: A jump-host SSH server that starts machines on-demand</em>. What it enables is pretty magical. It essentially lets you run arbitrary code when something SSHs through the jump-host.</p> Let's take the classic ZFS replication example from the docs</a>: host1# zfs send tank/dana@snap1 | ssh host2 zfs recv newtank/dana</code>. This command copies a snapshot from a machine named host1</code> to another machine named host2</code> over SSH. Simple and secure backups. But it relies on host2</code> being available. With lazyssh</code> we can make host2</code> only exist when needed. host2</code> would start when the ssh command is invoked and terminated when the ssh command finishes. The command with lazyssh</code> would look something like this (assuming you have a lazyssh</code> target in your .ssh/config</code> as explained in the docs</a>):</p> host1# zfs send tank/dana@snap1 | ssh -J lazyssh host2 zfs recv newtank/dana </code></pre> Note the only difference is the -J lazyssh</code>.</p> So how do we actually setup lazyssh</code> to do this? Here is my configuration:</p>

`Fin</h2> That's it. Just a small post for a neat little trick. If you set this up let me know! I'm interested in hearing your use case.</p> Footnotes</h3> ^{1</sup> User/pass = root/root. Exit qemu with C-a x.</p> </div>}`

Footnotes</h3>
^{1</sup>
User/pass = root/root. Exit qemu with C-a x.</p>
</div>}

MarcoPolo – Partially Functional - Nix

Declarative Dev Environments

Closing thoughts</h2>
In modern programming languages we define all our dependencies explicitly and lock the specific versions used. It's about time we do that for all our tools too. Let's get rid of the `apt-get install</code> and brew install</code> section of READMEs.</p>`

Simple Declarative VMs

Backups made simple

MarcoPolo – Partially Functional - Nix

Declarative Dev Environments

Simple Declarative VMs

Fin</h2> That's it. Just a small post for a neat little trick. If you set this up let me know! I'm interested in hearing your use case.</p> Footnotes</h3> 1</sup> User/pass = root/root. Exit qemu with C-a x.</p> </div>

Footnotes</h3> 1</sup> User/pass = root/root. Exit qemu with C-a x.</p> </div>

Backups made simple

`Fin</h2> That's it. Just a small post for a neat little trick. If you set this up let me know! I'm interested in hearing your use case.</p> Footnotes</h3> ^{1</sup> User/pass = root/root. Exit qemu with C-a x.</p> </div>}`

Footnotes</h3>
^{1</sup>
User/pass = root/root. Exit qemu with C-a x.</p>
</div>}