✨ Puzzlevision ✨

Non-stop entertainment! The wackiest NixOS configuration to-date.

💡 Why the need for a second version?

At its core, version 2 of my NixOS flake was aimed at improving the following regions of my previous setup:

• Implementing my own custom library at self.lib, recursively built from the contents of the lib directory.
• Loading of systems from the systems directory, using easy-hosts.
  • Archetypes for various systems, as seen in Jake Hamilton's flake.
• Creating users in my systems through a unified NixOS module, with automated home-manager setups derived from the homes directory.

Since I am actively using this configuration on my main workstation and Server, things have mostly stabilized, leftover issues are sparse and the list of modules is nearing completion (for my purposes that is).

As such, I personally consider this flake production ready.

🚀 Deployment

To deploy a system run the following command in your terminal of choice.

sudo nixos-rebuild switch --flake .#hostname --accept-flake-config

If you're interested in a quick way to experiment with this configuration, you may use the following command to build a VM.

sudo nixos-rebuild build-vm --flake .#hostname --accept-flake-config

🔑 Secrets Management

Secrets are managed by the sops-nix nixos/home-manager modules respectively.

• General secrets are stored within the secrets directory.
• System specific secrets are stored within their respective systems/<system_type>/<system_name>/secrets directory.

The following command may be used to convert the SSH host key of a new machine to an age key:

nix-shell -p ssh-to-age --run 'ssh-keyscan example.com | ssh-to-age'

Additionally, the following command may be used to create a new sops secret file:

nix-shell -p sops --run "sops secrets/example.yaml"

You may also encrypt arbitrary binary formats, like .cfg, using the following command:

Important

The original file location also HAS to match one of the sops creation rules, not just the output. Yes, I know this is stupid, and yes, I've wasted way too much time dealing with this :3

nix-shell -p sops --run "sops -e original_file.cfg > secrets/encrypted_file.cfg"

Lastly, when adding new systems, make sure to update any required secret files with the following command:

nix-shell -p sops --run "sops updatekeys secrets/example.yaml"

👷 CI/CD coverage

Currently, this repository houses 4 workflows, which are executed when pushing to the v2 branch.

↪️ Nix: check for unused code

This workflow can be found in .github/workflows/deadnix.yml, and should be pretty self-explanatory.

Here's what it does:

1. Checks out current branch
2. Finds any unused variables/imports etc...
3. Creates a new commit, instantly removing any unused code

↪️ Nix: validate flake

This workflow can be found in .github/workflows/validate.yml. It simply validates a flake using nix flake check.

To be specific, it does the following:

1. Checks out current branch
2. Installs nix with some experimental features (flakes, nix-command, recursive-nix, pipe-operator)
3. Runs nix flake check on the codebase

↪️ Nix: validate flake.lock

This workflow can be found in .github/workflows/validate-lock.yml. It simply scans flake lockfiles for duplicate entries using nix run github:tgirlcloud/pkgs#locker. Under the hood it makes use of the locker lockfile linter, created by the tgirlcloud team (mostly isabelroses).

To be specific, it does the following:

1. Checks out current branch
2. Installs nix with some experimental features (flakes, nix-command)
3. Runs nix run github:tgirlcloud/pkgs#locker on the codebase

↪️ Trufflehog: check for exposed secrets

This workflow can be found in .github/workflows/check-leaks.yml. It runs the Trufflehog security tools on the entire repository, and tries to detect any leaked credentials. This is a last barrier of defense to minimise damage, in case of an emergency.

📝 Future goals and improvements (2025-07-28)

Some of my future goals for this flake are:

• Implementing an automated release workflow with semver versioning, e.g. 2.3.0.
• Experimenting with various window-managers, especially Niri, though not set in stone yet.
• Researching performance best-practices for hardware and implementing patches based on those.
• Further refining my usage of the Nix language, through language best-practices and CLI dev tools.

🏗️ Structure

The structure this flake aims to build on is relatively simple to grasp.

flake.nix  --> The flake.
/systems   --> NixOS configurations for various types of systems, using easy-hosts.
/modules   --> Modules that are mapped to their corresponding easy-hosts class (and home modules).
  /nixos   --> (example) Modules specific to the nixos class configured in easy-hosts.
/homes     --> Directory for home-manager configurations, not specific to the system type.
/lib       --> A place for custom lib attributes exposed on the flake namespace (lib.puzzlevision.mkOpt).
(more...)  --> Additional directories have been considered (e.g. shells), but as of right now, they serve no use to me.

🎨 Credits

Parts of this flake were inspired by the likes of:

• isabelroses
• uncenter
• xaiyadev

and documentations such as:

• flake-parts
• NixOS and Flakes book
• The official NixOS wiki

many thanks to their hard work!