1
0
Fork 0
nix-configuration/README.md

145 lines
5.5 KiB
Markdown
Raw Normal View History

2024-02-29 09:53:34 -05:00
# NixOS Configuration
A full set of configuration files managed via NixOS. This project follows the general structure of https://github.com/tiredofit/nixos-config
2024-04-28 12:03:40 -04:00
> [!WARNING]
> DO NOT DOWNLOAD AND RUN `nixos-rebuild` ON THIS REPOSITORY! These are my personal configuration files. I invite you to look through them, modify them, and take inspiration from them, but if you run `nixos-rebuild`, it _will completely overwrite your current system_!
2024-03-22 18:18:38 -04:00
2024-05-10 12:53:17 -04:00
## Using this repo
2024-02-29 09:53:34 -05:00
### Note on secrets management
2024-05-23 23:50:42 -04:00
Secrets are stored in a separate repo called `nix-secrets`, which is included here as a flake input. This is a poor man's secret management solution, but y'know what, it works. These "secrets" will be readable to users on the system with access to the `/nix/store/`, but for single-user systems, it's fine.
2024-02-29 09:53:34 -05:00
Initialize the submodule with:
2024-02-29 09:53:34 -05:00
```sh
git submodule update --init --recursive
2024-02-29 09:53:34 -05:00
```
2024-05-10 12:53:17 -04:00
### First-time installation
2024-02-29 09:53:34 -05:00
To apply the config for the first time (e.g. on a fresh install), run these commands, replacing `Shura` with the name of the host:
2024-02-29 09:53:34 -05:00
```sh
nix flake update
sudo nixos-rebuild switch --flake .#Shura
```
`nix flake update` updates the `flake.lock` file, which pins repositories to specific versions. Nix will then pull down any derivations it needs to meet the version.
> [!NOTE]
> This config installs a [Nix wrapper called nh](https://github.com/viperML/nh). Basic install/upgrade commands can be run using `nh`, but more advanced stuff should use `nixos-rebuild`.
2024-02-29 09:53:34 -05:00
2024-05-10 12:53:17 -04:00
### Running updates
Periodically run `nh` to update the system. Use the `--update` flag to update `flake.lock` as part of the process. Note that for subsequent builds, you can omit the hostname:
2024-04-28 12:03:40 -04:00
```sh
2024-05-10 12:53:17 -04:00
nh os boot --update
2024-04-28 12:03:40 -04:00
```
2024-02-29 09:53:34 -05:00
2024-05-10 12:53:17 -04:00
This is the equivalent of running:
```sh
nix flake update
2024-05-10 12:53:17 -04:00
sudo nixos-rebuild boot --flake .
2024-02-29 09:53:34 -05:00
```
2024-05-10 12:53:17 -04:00
There are a few different actions for handling the update:
2024-05-10 12:53:17 -04:00
- `switch` replaces the running system immediately.
- `boot` switches to the new generation during the next reboot.
- `build` creates and caches the update without applying it.
- `test` creates the generation and switches to it, but doesn't add it to the bootloader.
2024-05-10 12:53:17 -04:00
#### Using Remote builds
Nix can create builds for or on remote systems, and transfer them via SSH.
##### Generating a build on a remote system
You can run a build on a remote server, then pull it down to the local system. This is called a `distributedBuild`.
> [!NOTE]
> For distributed builds, the root user on the local system needs SSH access to the build target. This is done automatically.
2024-05-10 12:53:17 -04:00
To enable root builds on a host, add this to its config:
```nix
nix.distributedBuilds = true;
```
2024-05-10 12:53:17 -04:00
For hosts where `nix.distributedBuilds` is true, this repo automatically gives the local root user SSH access to an unprivileged user on the build systems. This is configured in `nix-secrets`, but the build systems are defined in [`modules/base/nix.nix`](https://github.com/8bitbuddhist/nix-configuration/blob/b816d821636f9d30be905af80fe578c25ce74b92/modules/base/nix.nix#L41).
##### Pushing a build to a remote system
Conversely, you can run a build on the local host, then push it to a remote system.
```sh
NIX_SSHOPTS="-o RequestTTY=force" nixos-rebuild --target-host user@example.com --use-remote-sudo switch
```
2024-05-10 12:53:17 -04:00
### Testing without modifying the system
2024-04-28 12:03:40 -04:00
2024-05-10 12:53:17 -04:00
If you want to test without doing a whole build, or without modifying the current system, there are a couple additional tools to try.
2024-02-29 09:53:34 -05:00
2024-05-10 12:53:17 -04:00
#### Dry builds
To quickly validate your configuration, create a dry build. This analyzes your configuration to determine whether it'll actually build:
2024-02-29 09:53:34 -05:00
```zsh
nixos-rebuild dry-build --flake .
```
2024-05-10 12:53:17 -04:00
#### Virtual machines
You can also build a virtual machine image to preview changes. The first command builds the VM, and the second runs it:
2024-02-29 09:53:34 -05:00
```zsh
nixos-rebuild build-vm --flake .
2024-05-10 12:53:17 -04:00
./result/bin/run-nixos-vm
2024-02-29 09:53:34 -05:00
```
2024-05-10 12:53:17 -04:00
> [!NOTE]
> Running the VM also creates a `.qcow2` file for data persistence. Remove this file after a while, otherwise data might persist between builds and muck things up.
### Adding a host
To add a new host:
1. Create a new folder in `hosts/`.
2. Copy `hosts/configuration.nix.template` into this folder and name it `default.nix`.
3. Run `nixos-hardware-configuration` on the host and copy its `hardware-configuration.nix` file here. You might also want to check the `configuration.nix` generated by this command to see if there's anything you should import into your host's `default.nix`.
2024-05-23 23:50:42 -04:00
4. Configure `/hosts/<host>/default.nix` however you'd like.
2024-05-10 12:53:17 -04:00
5. Add the new host to `flake.nix`.
5. Run `nix flake update` and `nixos-rebuild boot --flake .#<Hostname>`.
## About this repository
### Layout
2024-02-29 09:53:34 -05:00
This config uses two systems: Flakes, and Home-manager.
2024-05-23 23:50:42 -04:00
- Flakes are the entrypoint, via `flake.nix`. This is where Flake inputs and Flake-specific options get defined.
- Home-manager configs live in the `users/` folders.
- Modules are stored in `modules`. All of these files are automatically imported (except home-manager modules); you simply enable the ones you want to use, and disable the ones you don't. For example, to install Flatpak, set `host.ui.flatpak.enable = true;`.
2024-05-04 10:40:10 -04:00
- After adding a new module, make sure to `git add` it.
2024-02-29 09:53:34 -05:00
2024-05-10 12:53:17 -04:00
### Features
2024-02-29 09:53:34 -05:00
This Nix config features:
- Flakes
- Home Manager
2024-05-23 23:50:42 -04:00
- AMD, Intel, and Raspberry Pi (ARM64) hardware configurations
2024-02-29 09:53:34 -05:00
- Workstation and server base system configurations
2024-05-10 12:53:17 -04:00
- GNOME desktop environment with KDE integrations
2024-02-29 09:53:34 -05:00
- Boot splash screens via Plymouth
2024-05-10 12:53:17 -04:00
- Secure Boot and TPM
2024-02-29 09:53:34 -05:00
- Disk encryption via LUKS
2024-05-23 23:50:42 -04:00
- Custom packages and systemd services
2024-02-29 09:53:34 -05:00
- Flatpaks
- Default ZSH shell using Oh My ZSH
2024-03-22 18:18:38 -04:00
- Secrets (in a janky hacky kinda way)