dotfiles/GUIDE.md

The Nix Documentation Situation

The Nix documentation situation is notorious bad. It's difficult to find a concise answer with detailed justification/explanation. And most people (myself included) tend resort to the ArchWiki.

Note

The Nix documentation team has an incredibly difficult job.

Unlike the centralised ArchWiki, the Nix ecosystem is incredibly large:

1. Nix (the package manager)
2. Nix/NixLang (the programming language)
3. Nixpkgs (the package repository)
4. NixOS (the linux distribution)
5. Home-Manager (user environment management)
6. NUR (Nix User Repository, like the AUR but Nix!)
7. and many more...

Often each project has its own website, wiki, styling, etc. There is tonnes of information available online but its so hard to find it.

Notable organisations:

1. NixOS Foundation (official organisation that maintains Nix/Nixpkgs/NixOS)
2. Nix Community (unofficial community providing infrastructure/hosting/visibility for projects)

About Me

I love and hate Nix simultaneously.

Originally (circa 2023) I used Windows 10/11 exclusively for programming. But this is tedious and my friend started mentioning Arch Linux. So with their help I formatted a spare SSD and began my journey.

But I REALLY like computers... I have servers, routers, 3 computers actively powered in my bedroom, and I believe 8 laptops currently in my posession.

Documenting every change I make to a system and spending a week setting up a device I don't really care about isn't sustainable. And then (circa October 2024) I learnt about NixOS... And now life is "easy". But learning Nix/NixLang/Nixpkgs/NixOS/Home-Manager/blah-blah-blah was exhausting. So now I'll try to simplify this learning curve for other newbies <3

Nix/NixOS How To

NixOS Documentation

Using "the" NixOS wiki is surprisingly confusing (at least it was for me). Why? Because there are multiple and you probably won't realise the difference.

Main Wikis:

These are visually and structurally identical... And are both community run. But they're content does differ. [nixos.wiki] was created because ""[wiki.nixos.org] was too limiting with regards to wiki features".

1. [https://wiki.nixos.org] (the official NixOS wiki)
2. [https://nixos.wiki] (the unofficial user's wiki, community run)

Other Resources:

[!TODO]

Migrate to a Newer Version of Nixpkgs

# Determine the channel name you're using
nix-channel --list
nix-channel --remove <OLD_CHANNEL>
nix-channel --add <NEW_CHANNEL> # ie https://nixos.org/channels/nixos-25.05
nix-channel --update

# Now upgrade system profile (log to file in case of failure)
nixos-rebuild boot --upgrade | tee rebuild.log

Security Implications

NixOS Default Home Permissions

# Executing from $HOME
>>> mkdir example.d && ls -l example.d
-rw-r--r-- 1 me users 1 Jul 25 10:13 example.d
>>> echo > example.f && ls -l example.f
-rw-r--r-- 1 me users 1 Jul 25 10:15 example.f

## But these ignore facl?
>>> getfacl "$HOME"
# file: home/me
# owner: me
# group: users
user::rwx
group::---
other::---

Many commands default to permissions that ignore the file access control listl (file ACLs). This is not a NixOS specific issue. However this isn't ideal from a security perspective. The simplest solution is a recursive chmod -R 600 ~ but there are plenty of files we intentionally want to be different.

[!TODO] Solution: Make a Nix/Home-Manager package allowing for control over folder permissions. SOlution: Also it should warn if any files owned by $USER have a 2

Further Reading

Finding New Things to Do

man 5 configuration.nix is incredibly useful similar info can be found at https://mynixos.com/options

For your curiosity

1. https://wiki.nixos.org/wiki/Firejail