thevoid.cafe
Non stop entertainment! The wackiest NixOS configuration to-date.
thevoid.cafe/projects/puzzlevision
nixos
flake
flake-parts
dotfiles
home-manager
nix
1<br>
2<div align="center"><img src=".tangled/assets/puzzlevision.png" width="120px" height="auto"></div>
3
4<h1 align="center">Puzzlevision<br></h1>
5<div align="center">Non-stop entertainment! The wackiest NixOS configuration to-date.</div>
6<br>
7
8## 💡 Why the need for a second version?
9At its core, version 2 of my NixOS flake was aimed at improving the following regions of my previous setup:
10
11- Implementing my own custom library at self.lib, recursively built from the contents of the `lib` directory.
12- Loading of systems from the `systems` directory, using easy-hosts.
13 - Archetypes for various systems, as seen in [Jake Hamilton's](https://github.com/jakehamilton) flake.
14- Creating users in my systems through a unified NixOS module, with automated home-manager setups derived from the `homes` directory.
15
16Since I am actively using this configuration on my main workstation and Server, things have mostly stabilized,
17leftover issues are sparse and the list of modules is nearing completion (for my purposes that is).
18
19As such, I personally consider this flake production ready.
20
21## 🚀 Deployment
22To deploy a system run the following command in your terminal of choice.
23
24```sh
25sudo nixos-rebuild switch --flake .#hostname --accept-flake-config
26```
27
28If you're interested in a quick way to experiment with this configuration,
29you may use the following command to build a VM.
30
31```sh
32sudo nixos-rebuild build-vm --flake .#hostname --accept-flake-config
33```
34
35## 🔑 Secrets Management
36Secrets are managed by the [sops-nix](https://github.com/Mic92/sops-nix) nixos/home-manager modules respectively.
37
38- General secrets are stored within the `secrets` directory.
39- System specific secrets are stored within their respective `systems/<system_type>/<system_name>/secrets` directory.
40- User secrets are stored within their respective `homes/<system_type>/<user_name>/secrets` directory.
41
42The following command may be used to convert the SSH host key of a new machine to an age key:
43
44```sh
45nix-shell -p ssh-to-age --run 'ssh-keyscan example.com | ssh-to-age'
46```
47
48Additionally, the following command may be used to create a new sops secret file:
49
50```sh
51nix-shell -p sops --run "sops secrets/example.yaml"
52```
53
54You may also encrypt arbitrary binary formats, like .cfg, using the following command:
55
56> [!IMPORTANT]
57> The original file location also HAS to match one of the sops creation rules, not just the output.
58> Yes, I know this is stupid, and yes, I've wasted way too much time dealing with this :3
59
60```sh
61nix-shell -p sops --run "sops -e original_file.cfg > secrets/encrypted_file.cfg"
62```
63
64Finally, when adding new systems, make sure to update any required secret files with the following command:
65
66```sh
67nix-shell -p sops --run "sops updatekeys secrets/example.yaml"
68```
69
70## 👷 CI/CD coverage
71Currently, this repository houses 4 workflows, which are executed when pushing to the stable/develop branch.
72
73#### ↪️ `Nix: check for unused code`
74This workflow can be found in `.tangled/workflows/deadnix.yml`,
75and should be pretty self-explanatory.
76
77Here's what it does:
781. Checks out current branch
792. Finds any unused variables/imports etc...
803. Creates a new commit, instantly removing any unused code
81
82#### ↪️ `Nix: validate flake`
83This workflow can be found in `.tangled/workflows/validate.yml`.
84It simply validates a flake using `nix flake check`.
85
86#### ↪️ `Nix: validate flake.lock`
87This workflow can be found in `.tangled/workflows/validate-lock.yml`.
88It simply scans flake lockfiles for duplicate entries using `nix run github:tgirlcloud/pkgs#locker`.
89Under the hood it makes use of the locker lockfile linter, created by the [tgirlcloud](https://github.com/tgirlcloud) team (mostly [isabelroses](https://github.com/isabelroses)).
90
91#### ↪️ `Trufflehog: check for exposed secrets`
92This workflow can be found in `.tangled/workflows/trufflehog-scan.yml`.
93It runs the Trufflehog security tools on the entire repository, and tries to detect any leaked credentials.
94This is a last barrier of defense to minimize damage, in case of an emergency.
95
96## 📝 Future goals (2026-02-22)
97Some of my future goals for this flake are:
98
99- Implementing an automated release workflow with semver versioning, e.g. 2.3.0.
100- Further refining my usage of the Nix language, through language best-practices and CLI dev tools.
101
102## 🏗️ Structure
103This flake follows an opinionated directory structure, described below.
104
105```
106flake.nix --> The flake.
107/systems --> NixOS configurations for various types of systems, using easy-hosts.
108/modules --> Modules that are mapped to their corresponding easy-hosts class (and home modules).
109 /nixos --> (example) Modules specific to the nixos class configured in easy-hosts.
110/homes --> Directory for home-manager configurations, not specific to the system type.
111/lib --> A place for custom lib attributes exposed on the flake namespace (lib.puzzlevision.mkOpt).
112(more...) --> Additional directories have been considered (e.g. shells), but as of right now, they serve no use to me.
113```
114
115## 🎨 Credits
116Various aspects of this flake are inspired by the likes of:
117
118- [isabelroses](https://github.com/isabelroses)
119- [uncenter](https://github.com/uncenter)
120- [xaiyadev](https://github.com/xaiyadev)
121
122and documentations such as:
123
124- [flake-parts](https://flake.parts)
125- [NixOS and Flakes book](https://nixos-and-flakes.thiscute.world)
126- [The official NixOS wiki](https://wiki.nixos.org)
127
128many thanks to their hard work!