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](https://wiki.archlinux.org).
> [!NOTE]
> The [Nix documentation team](https://nixos.org/community/teams/documentation) has an incredibly difficult job.

Unlike the *centralised* [ArchWiki](https://wiki.archlinux.org), 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
```bash
# 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
```bash
# 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