184 lines
7.4 KiB
Markdown
184 lines
7.4 KiB
Markdown
# Blake's NixOS configuration
|
|
|
|
This repository is the declarative source of truth for this NixOS system. It holds the configuration and the exact upstream input revisions used to build it. It does not hold private keys, passwords, encrypted disks, Docker data, browser profiles, or other mutable personal data.
|
|
|
|
## Current scope
|
|
|
|
The current flake exposes one host:
|
|
|
|
```sh
|
|
nixos
|
|
```
|
|
|
|
Use it as `'.#nixos'`. The repository currently contains that host's hardware-specific configuration in `hosts/nixos/hardware-configuration.nix`; it must not be used unchanged on another computer. A later reorganization will add one flake host entry per computer and move shared settings into common modules.
|
|
|
|
## The two important flake files
|
|
|
|
`flake.nix` is the recipe. It declares the inputs, NixOS modules, and configuration outputs.
|
|
|
|
`flake.lock` is the reproducibility record. It pins each input to an exact Git revision and content hash. It does not list individual packages. Because nixpkgs is locked, a normal rebuild does not silently upgrade Docker, Firefox, the kernel, or any other Nix-managed package.
|
|
|
|
The declared inputs follow matching NixOS and Home Manager 26.05 release branches. The lock file chooses the precise snapshot from those branches used by this system.
|
|
|
|
## Everyday workflow
|
|
|
|
Open this guide after the alias has been activated:
|
|
|
|
```sh
|
|
nix-guide
|
|
```
|
|
|
|
Edit the configuration as your normal user. Do not use `sudo` to edit files in this repository.
|
|
|
|
```sh
|
|
cd ~/nixos-config
|
|
$EDITOR hosts/nixos/configuration.nix
|
|
git diff
|
|
nix flake check --no-build
|
|
sudo nixos-rebuild switch --flake '.#nixos'
|
|
git add -A
|
|
git commit -m "Describe the configuration change"
|
|
git push
|
|
```
|
|
|
|
Only `nixos-rebuild switch` needs `sudo`: it creates and activates a new system generation. Editing, reviewing, committing, and pushing remain ordinary user actions. Keeping the repository user-owned prevents root-owned files and keeps Git usable without administrator privileges.
|
|
|
|
If a rebuild succeeds but the new system has a problem, select an earlier generation from the boot menu, or run:
|
|
|
|
```sh
|
|
sudo nixos-rebuild switch --rollback
|
|
```
|
|
|
|
## Updating packages safely
|
|
|
|
A rebuild uses the revisions already recorded in `flake.lock`; it is not a package update.
|
|
|
|
To request newer versions from the release branches declared in `flake.nix`:
|
|
|
|
```sh
|
|
cd ~/nixos-config
|
|
nix flake update
|
|
```
|
|
|
|
To update only NixOS packages, leaving other flake inputs unchanged:
|
|
|
|
```sh
|
|
nix flake update nixpkgs
|
|
```
|
|
|
|
Then review and test before activation:
|
|
|
|
```sh
|
|
git diff -- flake.lock
|
|
nix flake check --no-build
|
|
sudo nixos-rebuild switch --flake '.#nixos'
|
|
```
|
|
|
|
If the switch works as expected, commit the lock-file update:
|
|
|
|
```sh
|
|
git add flake.lock
|
|
git commit -m "Update flake inputs"
|
|
git push
|
|
```
|
|
|
|
A stable release branch normally receives compatible fixes and package updates. A move to a new NixOS release branch is a deliberate `flake.nix` change that must be built and tested before activation.
|
|
|
|
## Adding a program or service
|
|
|
|
1. Find the relevant NixOS or Home Manager option/package.
|
|
2. Add it to the appropriate `.nix` file.
|
|
3. Run `git diff` and read the change.
|
|
4. Run `nix flake check --no-build`.
|
|
5. Activate with `sudo nixos-rebuild switch --flake '.#nixos'`.
|
|
6. Verify the actual program or service works.
|
|
7. Commit and push the successful configuration.
|
|
|
|
Do not use `nix profile install` for persistent system software. Add persistent system packages to `environment.systemPackages` or use the relevant declarative option instead.
|
|
|
|
## SSH configuration and keys
|
|
|
|
SSH host aliases and connection settings can be declared through Home Manager and written to `~/.ssh/config`. The configuration may contain host names, users, ports, `ProxyJump`, and forwarding rules.
|
|
|
|
Private SSH keys never belong in this repository. Each computer should normally have its own key pair:
|
|
|
|
```sh
|
|
ssh-keygen -t ed25519 -a 100 -C "blake@<hostname>"
|
|
```
|
|
|
|
Install the resulting public key (`~/.ssh/id_ed25519.pub`) on the servers that machine may access. The declarative SSH config can refer to the local private-key path, but it must not contain the key itself. A lost or retired computer can then be revoked without affecting every other machine.
|
|
|
|
## New computer guide
|
|
|
|
Do not apply this repository's current `hosts/nixos/hardware-configuration.nix` to another computer. It contains this machine's encrypted-disk UUID, boot partition UUID, LVM layout, and CPU-specific settings.
|
|
|
|
The durable multi-host layout is the next structural improvement for this repository. Once it exists, use this process for every additional NixOS computer.
|
|
|
|
### 1. Prepare the new machine
|
|
|
|
1. Boot the official NixOS installer for the target architecture.
|
|
2. Connect to the network.
|
|
3. Decide the host name, disk layout, encryption policy, and whether the machine needs special hardware modules.
|
|
4. Partition, format, encrypt, and mount the disks under `/mnt` according to that machine's plan.
|
|
5. Generate a starter hardware configuration:
|
|
|
|
```sh
|
|
nixos-generate-config --root /mnt
|
|
```
|
|
|
|
6. Keep the generated `/mnt/etc/nixos/hardware-configuration.nix`. It is unique to that machine.
|
|
|
|
### 2. Create its host entry
|
|
|
|
On a trusted workstation or in the installer environment, clone this repository and create a host directory such as `hosts/<hostname>/`.
|
|
|
|
- Copy the generated hardware file into `hosts/<hostname>/hardware-configuration.nix`.
|
|
- Create a host module that imports the shared modules and that hardware file.
|
|
- Put only machine-specific choices there: hostname, disk/mount settings, bootloader, GPU/CPU-specific configuration, and hardware-only services.
|
|
- Add `nixosConfigurations.<hostname>` to `flake.nix`.
|
|
- Keep applications, desktop preferences, shell settings, and shared services in common modules so every machine receives the same tested setup.
|
|
|
|
Do not copy disk UUIDs, LUKS identifiers, swap-device paths, or a host name from another machine.
|
|
|
|
### 3. Install the declared configuration
|
|
|
|
After the target host output exists and the target root filesystem is mounted at `/mnt`, install using its own host selector:
|
|
|
|
```sh
|
|
sudo nixos-install --flake .#<hostname>
|
|
```
|
|
|
|
Set the initial user password if the configuration does not provision one declaratively, reboot, then log in to the installed system.
|
|
|
|
### 4. Bootstrap personal access
|
|
|
|
After first boot:
|
|
|
|
1. Generate a new SSH key pair for this computer.
|
|
2. Authorize its public key on the servers it should access.
|
|
3. Rebuild so Home Manager writes the declared SSH host aliases.
|
|
4. Verify each alias with a non-destructive command such as:
|
|
|
|
```sh
|
|
ssh -G <host-alias>
|
|
```
|
|
|
|
5. Restore personal data separately from the Nix configuration: documents, browser profiles if desired, Docker volumes/databases, and any encrypted secrets.
|
|
|
|
### 5. Verify before relying on it
|
|
|
|
Verify the things specific to that computer: boot, encrypted-disk unlock, networking, audio, graphics, Wi-Fi/Bluetooth, sleep, external drives, and any virtualization or GPU functionality. Confirm the flake evaluates and the working tree is committed:
|
|
|
|
```sh
|
|
cd ~/nixos-config
|
|
nix flake check --no-build
|
|
git status --short
|
|
git log --oneline -n 3
|
|
```
|
|
|
|
## Secrets and data not managed by this repository
|
|
|
|
Never commit private SSH keys, passwords, API tokens, VPN credentials, or unencrypted Wi-Fi secrets. When secrets need declarative deployment, add an encrypted secret system such as `sops-nix` or `agenix`.
|
|
|
|
NixOS generations are not backups for application data. Back up Docker volumes, databases, documents, and other mutable files independently.
|