diff --git a/content/blog/learn-flakes-the-fun-way.md b/content/blog/learn-flakes-the-fun-way.md new file mode 100644 index 0000000..0aff87f --- /dev/null +++ b/content/blog/learn-flakes-the-fun-way.md @@ -0,0 +1,382 @@ +--- +date: "2024-07-08T16:34:00-05:00" +title: "Learn Flakes the Fun Way" +draft: false +toc: false +--- + +This post is a Flake-based rewrite of [Learn Nix the Fun Way on fzakaria.com][0]. +I really enjoyed the content of the post and wanted to write it as a Nix +user who is just using and prefers Flakes. It does add a few extra steps and +complexity, but I think it's still valuable and perhaps reveals a bit more about +Nix and why it's pretty fantastic. I also include a few neat things that are +more Flake-specific at the end. + +But yes, it's basically plagiarism. + + + +## what-is-my-ip + +Let's walk through a single example of a shell script one may write, `what-is-my-ip`: + +```bash +#!/usr/bin/env bash +curl -s http://httpbin.org/get | jq --raw-output .origin +``` + +Sure, it's _sort of portable_, if you tell the person running it to have _curl_ and _jq_. What if you relied on a specific version of either, though? + +Nix **guarantees** portability. + +We might leverage _[Nixpkgs' trivial builders](https://ryantm.github.io/nixpkgs/builders/trivial-builders/)_ (specifically, `writeShellScriptBin`) in a basic Nix Flake to turn this into a Nix derivation (i.e. build recipe): + +```nix +# flake.nix +{ + inputs.nixpkgs.url = "nixpkgs/nixos-24.05"; + outputs = {nixpkgs, ...}: let + systems = ["aarch64-linux" "aarch64-darwin" "x86_64-darwin" "x86_64-linux"]; + pkgsFor = func: (nixpkgs.lib.genAttrs systems (system: (func (import nixpkgs {inherit system;})))); + in { + packages = pkgsFor (pkgs: { + default = pkgs.callPackage ./what-is-my-ip.nix {}; + }); + }; +} +``` + +```nix +# what-is-my-ip.nix +{pkgs}: +pkgs.writeShellScriptBin "what-is-my-ip" '' + ${pkgs.curl}/bin/curl -s http://httpbin.org/get | ${pkgs.jq}/bin/jq --raw-output .origin +'' +``` + +> 😬 Avoid over-focusing on the fact I just introduced a new language and a good chunk of boilerplate. Just come along for the ride. + +Here we are pinning our package to dependencies which come from NixOS/Nixpkgs release branch 24.05. + +We can build our package and find out the Nix store path (which contains the +hash) like so: + +```console +$ nix build --print-out-paths +/nix/store/lr6wlz2652r35rwzc79samg77l6iqmii-what-is-my-ip +``` + +And, of course, we can run our built result: + +```console +$ ./result/bin/what-is-my-ip +24.5.113.148 +``` + +Or run it from the Flake directly: + +```console +$ nix run +24.5.113.148 +``` + +### Graph Dependencies + +Now that this is in our Nix store, we've naturally modeled our dependencies +and can do _fun_ things like generate graph diagrams: + +```console +$ nix-store --query --graph $(readlink result) | nix shell nixpkgs#graphviz -c dot -Tpng -o what-is-my-ip-deps.png +``` + +[![Image of what-is-my-ip dependencies as a graph](/img/what-is-my-ip-deps.png)](/img/what-is-my-ip-deps.png) + +### Developer Environments + +Let's add a _developer environment_ which contains our new tool. +This is a great way to create developer environments with reproducible tools. +Generally, though, `devShells` are for working _on_ the product of the Flake and +do not _usually_ include the product itself. + +```diff +diff --git a/flake.nix b/flake.nix +index 2a99357..ab32421 100644 +--- a/flake.nix ++++ b/flake.nix +@@ -1,11 +1,24 @@ + { + inputs.nixpkgs.url = "nixpkgs/nixos-24.05"; +- outputs = {nixpkgs, ...}: let ++ outputs = { ++ self, # we will need to reference our own outputs to pull in the package we've declared ++ nixpkgs, ++ ... ++ }: let + systems = ["aarch64-linux" "aarch64-darwin" "x86_64-darwin" "x86_64-linux"]; + pkgsFor = func: (nixpkgs.lib.genAttrs systems (system: (func (import nixpkgs {inherit system;})))); + in { + packages = pkgsFor (pkgs: { + default = pkgs.callPackage ./what-is-my-ip.nix {}; + }); ++ ++ devShells = pkgsFor (pkgs: { ++ default = pkgs.mkShell { ++ packages = [self.outputs.packages.${pkgs.system}.default]; ++ shellHook = '' ++ echo "Hello, Nix!" ++ ''; ++ }; ++ }); + }; + } +``` + +```console +$ nix develop -c $SHELL +Hello, Nix! + +$ which what-is-my-ip +/nix/store/lr6wlz2652r35rwzc79samg77l6iqmii-what-is-my-ip/bin/what-is-my-ip +``` + +🕵️ Notice that the hash `lr6wlz2652r35rwzc79samg77l6iqmii` is _exactly_ the same which we built earlier. + +### Deployment + +We can now do binary or source deployments 🚀🛠️📦 since we know the full dependency closure of our tool. We simply copy the necessary `/nix/store` paths to another machine with Nix installed. + +```console +$ nix copy --to ssh://beefcake $(nix build --print-out-paths) +$ ssh beefcake /nix/store/lr6wlz2652r35rwzc79samg77l6iqmii-what-is-my-ip/bin/what-is-my-ip +98.147.178.19 +``` + +#### With Containers + +Maybe though you are stuck with Kubernetes or Docker. Let's use Nix to create an OCI-compatible image with our tool: + +```diff +diff --git a/flake.nix b/flake.nix +index 99d6d52..81e98c9 100644 +--- a/flake.nix ++++ b/flake.nix +@@ -10,6 +10,12 @@ + in { + packages = pkgsFor (pkgs: { + default = pkgs.callPackage ./what-is-my-ip.nix {}; ++ container = pkgs.dockerTools.buildImage { ++ name = "what-is-my-ip-container"; ++ config = { ++ Cmd = ["${self.outputs.packages.${pkgs.system}.default}/bin/what-is-my-ip"]; ++ }; ++ }; + }); + + devShells = pkgsFor (pkgs: { +``` + +```console +$ docker load < $(nix build .#container --print-out-paths) +Loaded image: what-is-my-ip-docker:c9g6x30invdq1bjfah3w1aw5w52vkdfn +$ docker run -it what-is-my-ip-container:c9g6x30invdq1bjfah3w1aw5w52vkdfn +24.5.113.148 +``` + +Cool! Nix + Docker integration perfectly. The image produced has only the files exactly necessary to run the tool provided, effectively **distroless**. You may also note that if you are following along, your image digest is exactly the same. **Reproducibility!** + +#### In Virtual Machines + +Finally, let's take the last step and create a reproducible operating system using NixOS to contain only the programs we want: + +```diff +diff --git a/flake.nix b/flake.nix +index 99d6d52..81e98c9 100644 +--- a/flake.nix ++++ b/flake.nix +@@ -20,5 +26,27 @@ + ''; + }; + }); ++ ++ nixosConfigurations = let ++ system = "x86_64-linux"; ++ in { ++ default = nixpkgs.lib.nixosSystem { ++ inherit system; ++ modules = [ ++ { ++ users.users.alice = { ++ isNormalUser = true; ++ # enable sudo ++ extraGroups = ["wheel"]; ++ packages = [ ++ self.outputs.packages.${system}.default ++ ]; ++ initialPassword = "swordfish"; ++ }; ++ system.stateVersion = "24.05"; ++ } ++ ]; ++ }; ++ }; + }; + } +``` + +Now we can run this NixOS configuration as a reproducible virtual machine: + +```console +$ nixos-rebuild build-vm --flake .#default +$ ./result/bin/run-nixos-vm + +# I/O snippet from QEMU +nixos login: alice +Password: + +$ readlink $(which what-is-my-ip) +/nix/store/lr6wlz2652r35rwzc79samg77l6iqmii-what-is-my-ip/bin/what-is-my-ip + +$ what-is-my-ip +24.5.113.148 +``` + +💥 Hash `lr6wlz2652r35rwzc79samg77l6iqmii` present again! + +We took a relatively simple script through a variety of applications in the Nix ecosystem: build recipe, shell, docker image, and finally NixOS VM. + +## Flakes as All Kinds of Package Management + +One of the super neat part about Flakes is that anywhere you find a Flake, you +can make use of it. Try it out now! + +> **NOTE**: The following obviously runs code from the internet. Be wary of doing this in general. + +Run a Flake's package: + +```console +$ nix run git+https://git.lyte.dev/lytedev/learn-flakes-the-fun-way +24.5.113.148 +``` + +Enter a Flake's development environment: + +```console +$ nix develop git+https://git.lyte.dev/lytedev/learn-flakes-the-fun-way -c $SHELL +Hello, Nix! +$ what-is-my-ip +24.5.113.148 + +# want to hack on the Helix text editor? +$ nix develop github:helix-editor/helix +# yeah, seriously! that's it! +``` + +Load a Flake's docker image and run it: + +```console +$ docker load < $(nix build git+https://git.lyte.dev/lytedev/learn-flakes-the-fun-way#container --print-out-paths) +Loaded image: what-is-my-ip-container:wg0z43v4sc1qhq7rsqg02w80vsfk9dl0 +$ docker run -it what-is-my-ip-container:c9g6x30invdq1bjfah3w1aw5w52vkdfn +``` + +Run a Flake's NixOS configuration as a virtual machine: + +```console +$ nixos-rebuild build-vm --flake git+https://git.lyte.dev/lytedev/learn-flakes-the-fun-way#default +Done. The virtual machine can be started by running /nix/store/xswwdly9m5bwhcz9ajd6km5hx9vdmfzw-nixos-vm/bin/run-nixos-vm +$ /nix/store/xswwdly9m5bwhcz9ajd6km5hx9vdmfzw-nixos-vm/bin/run-nixos-vm +``` + +Run an exact replica my workstation in a virtual machine (as configured via Nix +-- meaning it will not have my passwords on it 😉): + +```console +# NOTE: this will probably take a good, long time to build and lots of bandwidth +# NOTE: you probably won't even be able to login +$ nixos-rebuild build-vm --flake git+https://git.lyte.dev/lytedev/nix#dragon +Done. The virtual machine can be started by running /nix/store/abc-nixos-vm/bin/run-dragon-vm +$ /nix/store/abc-nixos-vm/bin/run-dragon-vm +``` + +## Flakes as Inputs + +Finally, Flakes can take any other Flake as input and use them for their own outputs. This means that they compose wonderfully. Any Flake can use anything from any other Flake. They're basically big ol' distributed functions (if you squint just right). `nixpkgs` itself is "simply" a huge Flake. + +You can generate your own Flake however you like; Flakes provide templating +facilities. Here, you can use my very own template: + +```console +$ mkdir -p ~/my-fun-flake +$ cd ~/my-fun-flake +$ nix flake init --template git+https://git.lyte.dev/lytedev/nix#nix-flake +$ git init +$ git add -A +$ git commit -am 'initial commit' +$ nix develop -c $SHELL +``` + +And now you have everything you need to work on a Nix flake as if you were me! + +To add the package from this tutorial, we can simply do this: + +```diff +diff --git a/flake.nix b/flake.nix +index 408d4f2..c5d6883 100644 +--- a/flake.nix ++++ b/flake.nix +@@ -2,16 +2,20 @@ + inputs.pre-commit-hooks.url = "github:cachix/pre-commit-hooks.nix"; + inputs.pre-commit-hooks.inputs.nixpkgs.follows = "nixpkgs"; + ++ inputs.learn-flakes-the-fun-way.url = "git+https://git.lyte.dev/lytedev/learn-flakes-the-fun-way"; ++ inputs.learn-flakes-the-fun-way.inputs.nixpkgs.follows = "nixpkgs"; ++ + outputs = { + self, + nixpkgs, + pre-commit-hooks, ++ learn-flakes-the-fun-way, + ... + }: let + systems = ["aarch64-linux" "aarch64-darwin" "x86_64-darwin" "x86_64-linux"]; + forSystems = nixpkgs.lib.genAttrs systems; + in { + formatter = genPkgs (pkgs: pkgs.alejandra); + +@@ -26,7 +30,7 @@ + + devShells = genPkgs (pkgs: { + nix = pkgs.mkShell { +- packages = with pkgs; [nil alejandra]; ++ packages = with pkgs; [nil alejandra learn-flakes-the-fun-way.packages.${pkgs.system}.default]; + inherit (self.outputs.checks.${pkgs.system}.pre-commit-check) shellHook; + }; + +``` + +Afterwards you can re-enter your development shell and run our script: + +```console +$ nix develop -c $SHELL +$ what-is-my-ip +24.5.113.148 +``` + +## Other Flakey (but in a good way) Tools + +On top of all this, many very awesome tools can exist. You can leverage a `direnv`-style setup such that whenever you enter a directory you enter its development shell and are completely ready to work within that project with all the necessary tools with all the correct versions _reproducibly_. + +Flakes have `checks` which are run when you run `nix flake check`. You can use this for CI to ensure that your Flake is always able to build whatever packages it needs or even check that code is formatted correctly. + +All of this in one place makes for a pretty incredible developer experience. + +## Conclusion + +Hopefully, seeing the _fun things_ you can do with Nix might inspire you to push through the hard parts. + +There is a golden pot 💰 at the end of this rainbow 🌈 awaiting you. + +**Learn Flakes the fun way.** + +[0]: https://fzakaria.com/2024/07/05/learn-nix-the-fun-way.html + diff --git a/src/stylus/core.styl b/src/stylus/core.styl index fc740e8..e2140c3 100644 --- a/src/stylus/core.styl +++ b/src/stylus/core.styl @@ -271,6 +271,11 @@ form max-width 100vw overflow-x auto +blockquote > p + padding 1em + background-color var(--Mantle) + border-left solid var(--syntax-bpx) var(--Surface1) + @media (min-width 600px) body.align-left .hide-in-align-left { display: none } diff --git a/src/stylus/theme.styl b/src/stylus/theme.styl index c5b3203..36db5f5 100644 --- a/src/stylus/theme.styl +++ b/src/stylus/theme.styl @@ -19,10 +19,38 @@ mocha = { /* TODO: everything should be a catppuccin color or based on one */ light-theme = { + --Rosewater: #dc8a78, + --Flamingo: #dd7878, + --Pink: #ea76cb, + --Mauve: #8839ef, + --Red: #d20f39, + --Maroon: #e64553, + --Peach: #fe640b, + --Yellow: #df8e1d, + --Green: #40a02b, + --Teal: #179299, + --Sky: #04a5e5, + --Sapphire: #209fb5, + --Blue: #1e66f5, + --Lavender: #7287fd, + --Text: #4c4f69, + --Subtext1: #5c5f77, + --Subtext0: #6c6f85, + --Overlay2: #7c7f93, + --Overlay1: #8c8fa1, + --Overlay0: #9ca0b0, + --Surface2: #acb0be, + --Surface1: #bcc0cc, + --Surface0: #ccd0da, + --Base: #eff1f5, + --Mantle: #e6e9ef, + --Crust: #dce0e8, + --syntax-brd: rgba(255, 255, 255, 0.2), --syntax-bg: #e6e9ef, --syntax-ledg: rgba(0, 0, 0, 0.1), --syntax-ledg: rgba(0, 0, 0, 0.3), + --syntax-ledgbq: rgba(0, 0, 0, 0.3), --syntax-sh: #6c6f85, --syntax-name: latte['green'], --syntax-mag: latte['red'], @@ -49,10 +77,38 @@ light-theme = { } dark-theme = { + --Rosewater: #f5e0dc, + --Flamingo: #f2cdcd, + --Pink: #f5c2e7, + --Mauve: #cba6f7, + --Red: #f38ba8, + --Maroon: #eba0ac, + --Peach: #fab387, + --Yellow: #f9e2af, + --Green: #a6e3a1, + --Teal: #94e2d5, + --Sky: #89dceb, + --Sapphire: #74c7ec, + --Blue: #89b4fa, + --Lavender: #b4befe, + --Text: #cdd6f4, + --Subtext1: #bac2de, + --Subtext0: #a6adc8, + --Overlay2: #9399b2, + --Overlay1: #7f849c, + --Overlay0: #6c7086, + --Surface2: #585b70, + --Surface1: #45475a, + --Surface0: #313244, + --Base: #1e1e2e, + --Mantle: #181825, + --Crust: #11111b, + --syntax-brd: rgba(255, 255, 255, 0.2), --syntax-bg: #181825, --syntax-ledg: alpha(mocha['sapphire'], 0.5), --syntax-ledgh: mocha['sapphire'], + --syntax-ledgbq: mocha['surface1'], --syntax-sh: #6c7086, --icon-shadow: #000, --syntax-name: mocha['green'], diff --git a/static/global.mjs b/static/global.mjs index 493a23b..8656b2e 100644 --- a/static/global.mjs +++ b/static/global.mjs @@ -82,7 +82,7 @@ function initCodeCopyButtons() { } window.addEventListener("load", initAlign); -window.addEventListener("load", initCodeCopyButtons); +// window.addEventListener("load", initCodeCopyButtons); window.addEventListener("DOMContentLoaded", () => { document.querySelectorAll(".nojs").forEach(e => { e.classList.remove("nojs") diff --git a/static/img/what-is-my-ip-deps.png b/static/img/what-is-my-ip-deps.png new file mode 100644 index 0000000..82246f1 Binary files /dev/null and b/static/img/what-is-my-ip-deps.png differ