doc: Add a short introduction and basic installation/usage instructions.
This commit is contained in:
parent
6615f5c13d
commit
3f59316065
GPG key ID:
C0F1D326C7626543
2 changed files with 252 additions and 54 deletions
252
README.md
Normal file
252
README.md
Normal 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
54
README.org
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue