derped/nixos
1
0
Fork 0
Code Releases Activity

doc: Add a short introduction and basic installation/usage instructions.

Browse source
This commit is contained in:
Kevin Baensch 2025-07-12 14:34:38 +02:00
parent 6615f5c13d
commit 3f59316065
Signed by: derped
GPG key ID: C0F1D326C7626543
2 changed files with 252 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

252
README.md Normal file
View file

@ -0,0 +1,252 @@
# Yet Another NixOS Configuration
## Introduction
This is my [NixOS](https://nixos.org/) configuration, it provides an abstraction from the
already existing options on NixOS. To be more precise it is a
collection of pre-configured services and meta-packages that can be
toggled and configured through a single NixOS module.
It's flexible enough to manage *all* my machines (multiple server and
desktop configurations).
## Getting Started
The following instructions are for a fresh NixOS installation.
1. (Optional) **Partition Layout for Impermanence + Btrfs**
1. Btrfs
Format your `root` partition as Btrfs.
Remember to add `"btrfs"` (and `"btrbk"` if you use impermanence) to `config.machine.services` in step 3.
1. Impermanence
> [!WARNING]
> Many services are not yet configured for impermanence.
> You will likely have to add your desired state to the [impermanence service](./services/impermanence.nix)
For [impermanence](https://github.com/nix-community/impermanence) to work you will have to:
Your system root (`/`) should be either a `tmpfs` mount or has to be [deleted during boot](https://github.com/nix-community/impermanence?tab=readme-ov-file#btrfs-subvolumes).
Create at least the following folders (or subvolumes if you're using Btrfs) on your disk:
- `/nix` for the nix store
- `/persist` to store persistent folders to be mounted by impermanence
- `/tmp` mainly because [nix builds use /tmp by default](https://github.com/NixOS/nixpkgs/issues/54707)
- `/snapshots` to store snapshots if you are using `btrbk`
Remember to add `"impermanence"` to `config.machine.services` in step 3.
1. **Generate your base configuration.**
By either taking your existing configuration or following the [NixOS Installation Manual](https://nixos.org/manual/nixos/stable/#sec-installation-manual) until `nixos-generate-config`.
You should have the files:
- `configuration.nix`
- `hardware-configuration.nix`
Adjust the mounts inside your `hardware-configuration.nix` to fit your setup.
Here is a configuration template assuming an encrypted Btrfs partition and impermanence:
```nix
{
nixpkgs,
config,
pkgs,
modulesPath,
nixos-hardware,
...
}:
{
imports = [
(modulesPath + "/installer/scan/not-detected.nix")
# check https://github.com/NixOS/nixos-hardware or remove
nixos-hardware.nixosModules.YOUR_DEVICE_HERE
];
boot = {
loader.systemd-boot = {
enable = true;
};
loader.efi.canTouchEfiVariables = true;
supportedFilesystems = [ "btrfs" ];
# modify/add initrd and kernelModules to your needs
initrd = {
availableKernelModules = [ ];
luks.devices."btrfs-crypt".device = "/dev/disk/by-uuid/DEVICE_UUID";
};
kernelModules = [ ];
};
fileSystems = {
"/" = {
device = "none";
fsType = "tmpfs";
options = [
"defaults"
"size=512M"
"mode=755"
];
};
"/tmp" = {
device = "/dev/mapper/btrfs-crypt";
fsType = "btrfs";
options = [
"subvol=tmp"
"noatime"
"compress=zstd"
];
neededForBoot = true;
};
"/persist" = {
device = "/dev/mapper/btrfs-crypt";
fsType = "btrfs";
options = [
"subvol=persist"
"noatime"
"compress=zstd"
];
neededForBoot = true;
};
"/nix" = {
device = "/dev/mapper/btrfs-crypt";
fsType = "btrfs";
options = [
"subvol=nix"
"noatime"
"compress=zstd"
];
neededForBoot = true;
};
"/snapshots" = {
device = "/dev/mapper/btrfs-crypt";
fsType = "btrfs";
options = [
"subvol=snapshots"
"noatime"
"compress=zstd"
];
neededForBoot = false;
};
"/boot" = {
device = "/dev/disk/by-uuid/546A-A3D1";
fsType = "vfat";
options = [
"fmask=0022"
"dmask=0022"
];
};
};
# add hardware power policies and timezone
}
```
1. **Define `options.nix` for your Machine**
> [!NOTE]
> This section needs to be expanded.
> Ideally I just refine the machine module, implement generating docs and refer to there.
```nix
_:
{
config.machine = {
allowUnfree = true;
hostName = "<hostname>";
users = [
{
name = "<username>";
isAdmin = true;
pkgs = [];
services = [];
}
];
conffiles = [
"etcfiles"
"etcvars"
"fonts"
"zsh"
];
pkgs = [
"base"
];
services = [
"desktop"
"desktop::sway"
"openssh"
"pipewire"
"tmux"
];
};
}
```
1. **Set up Sops.**
Secret management throughout this project is handled with [sops-nix](https://github.com/Mic92/sops-nix).
If you are unfamiliar with [sops](https://github.com/getsops/sops), read the [sops documentation](https://getsops.io/docs/)
Adjust the `.sops.yaml` file to your needs.
Generate your machine key in a persistent location (adjust if you are not using impermanence):
```bash
mkdir -p /mnt/persist/var/lib/;
cd /mnt/persist/var/lib/;
# create a subvolume so the key is not included in snapshots
btrfs subvolume create sops-nix;
chmod 700 sops-nix;
# make sure age is in your path
age-keygen -o sops-nix/key.txt
```
In your machine folder add the files:
- sops.nix
```nix
_:
{
sops = {
defaultSopsFile = ./secrets.yaml;
age = {
keyFile = "/persist/var/lib/sops-nix/key.txt";
generateKey = true;
};
};
}
```
- secrets.yaml
You can get a rough overview of all sops secrets by grepping the repository for `sops.secrets`.
Or you can list the required secrets for your current configuration by running the following command (adjust host name):
```bash
nix eval .\#nixosConfigurations.$(hostname).config.sops.secrets --json | jq 'keys'
```
Edit your secrets by running (adjust the path to your key and `secrets.yaml`):
```bash
SOPS_AGE_KEY_FILE="/mnt/persist/var/lib/sops-nix/key.txt" sops edit machines/$(hostname)/secrets.yaml
```
A minimal secret configuration for a single user with the `openssh` service enabled may look like this:
```yaml
users:
MY_USER_NAME:
password: PASSWORD_HASH_FROM_MKPASSWD
publicKey: ssh-ed25519 PUB_KEY PUB_KEY_COMMENT
```

54
README.org
View file

@ -1,54 +0,0 @@
#+LANGUAGE: en
#+AUTHOR: Baensch, Kevin
#+EMAIL: mailto://derped[at]ophanim[dot]de
*THIS README IS A WIP IF YOU DON'T KNOW WHAT YOU ARE DOING YOU PROBABLY WONT GET IT TO RUN ON YOUR SYSTEM.*
* TODO Introduction
This is my [[https://nixos.org/][NixOS]] configuration, it provides an abstraction from the
already existing options on NixOS. To be more precise it is a
collection of preconfigured services and metapackages that can be
toggled and configured through a single NixOS submodule.
It's flexible enough to manage *all* my machines (multiple Servers and
Desktops).
Currently the following services are configured:
- Desktop
- i3
- MySQL/MariaDB
- cups
- fail2ban
- nginx
- Nextcloud
- Gitea
- Hydra (works but could be better)
- openssh
** TODO Getting Started/Setup Guide
- *WARNING:* :: I still change machine option names rather frequently
and whilst it works for me it may break for you. You
have been warned.
*** Nixpkgs Channels
/See [[https://nixos.org/channels/][NixOS Channels]]./
This Project references 4 channels:
- nixos :: Your main channel, can be any NixOS channel of your choosing.
- nixos-stable :: Should point to the current NixOS/NixOS-small channel.
- nixos-unstable :: Should point to [[https://nixos.org/channels/nixos-unstable][nixos-unstable]] or [[https://nixos.org/channels/nixos-unstable-small][nixos-unstable-small]].
- gitpkgs :: A copy of the current [[https://github.com/nixos/nixpkgs][nixpkgs git repo]] cloned into you system root.
Currently these channels are only referenced in [[./pkgs/pkgsets.nix][pkgsets.nix]]. It can
be easily replaced and is therefore optional (but recommended).
#+begin_src shell
nix-channel --add https://nixos.org/channels/nixos-unstable nixos
nix-channel --add https://nixos.org/channels/nixos-19.09 nixos-stable
nix-channel --add https://nixos.org/channels/nixos-unstable nixos-unstable
nix-channel --update
git clone https://github.com/nixos/nixpkgs /nixpkgs
#+end_src
* TODO Submodule Documentation
- [TODO] Create a setup script.
All Submodules are defined in [[./options][options]].
** machines
** copySysConf