176 lines
4.0 KiB
Markdown
Executable File
176 lines
4.0 KiB
Markdown
Executable File
# Getting Started
|
|
|
|
This guide will help you get started with this NixOS configuration repository.
|
|
|
|
## Prerequisites
|
|
|
|
- Basic knowledge of NixOS and the Nix language
|
|
- Git installed on your system
|
|
- Physical or SSH access to the target machine
|
|
|
|
## Cloning the Repository
|
|
|
|
```bash
|
|
git clone ssh://nix-apps@localhost:2222/mjallen/nix-config.git
|
|
cd nix-config
|
|
```
|
|
|
|
## Installing on a New Machine
|
|
|
|
### Option 1: Using an existing system configuration
|
|
|
|
If the machine matches an existing configuration (e.g. reinstalling `jallen-nas`):
|
|
|
|
1. Boot from a NixOS installation ISO
|
|
2. Partition and mount disks (or use `disko`):
|
|
```bash
|
|
nix run github:nix-community/disko -- --mode disko /path/to/disko-config.nix
|
|
```
|
|
3. Clone this repo into the target:
|
|
```bash
|
|
mkdir -p /mnt/etc/nixos
|
|
git clone <repo-url> /mnt/etc/nixos
|
|
```
|
|
4. Install:
|
|
```bash
|
|
nixos-install --flake /mnt/etc/nixos#hostname
|
|
```
|
|
|
|
### Option 2: Adding a new system configuration
|
|
|
|
1. **Create the system directory** under the appropriate architecture:
|
|
```bash
|
|
mkdir -p systems/x86_64-linux/new-hostname
|
|
```
|
|
|
|
2. **Write the configuration** — at minimum a `default.nix`:
|
|
```nix
|
|
{ namespace, ... }:
|
|
{
|
|
mjallen = {
|
|
sops.enable = true;
|
|
network.hostName = "new-hostname";
|
|
user.name = "admin";
|
|
};
|
|
}
|
|
```
|
|
|
|
3. **Generate hardware configuration** (on the target machine):
|
|
```bash
|
|
nixos-generate-config --no-filesystems --dir systems/x86_64-linux/new-hostname/
|
|
```
|
|
|
|
4. **Add SOPS secrets** for the new host — see [Secrets Management](../README.md#secrets-management).
|
|
|
|
5. **Build and switch**:
|
|
```bash
|
|
sudo nixos-rebuild switch --flake .#new-hostname
|
|
```
|
|
|
|
## Day-to-Day Usage
|
|
|
|
### Applying configuration changes
|
|
|
|
```bash
|
|
# On the local machine
|
|
sudo nixos-rebuild switch --flake .#$(hostname)
|
|
|
|
# On a remote machine
|
|
nixos-rebuild switch --flake .#hostname --target-host user@host --use-remote-sudo
|
|
```
|
|
|
|
### Updating flake inputs
|
|
|
|
```bash
|
|
# Update all inputs
|
|
nix flake update
|
|
|
|
# Update a single input
|
|
nix flake lock --update-input nixpkgs
|
|
|
|
# Apply after updating
|
|
sudo nixos-rebuild switch --flake .#$(hostname)
|
|
```
|
|
|
|
### Garbage collection
|
|
|
|
```bash
|
|
# Remove old generations and unreferenced store paths
|
|
sudo nix-collect-garbage -d
|
|
|
|
# Keep the last N generations
|
|
sudo nix-collect-garbage --delete-older-than 30d
|
|
```
|
|
|
|
## Enabling a Module
|
|
|
|
Most functionality is exposed through the `mjallen` namespace. To enable a module, set it in the system's `default.nix` (or a relevant sub-file):
|
|
|
|
```nix
|
|
mjallen = {
|
|
desktop.gnome.enable = true;
|
|
hardware.amd.enable = true;
|
|
gaming.enable = true;
|
|
|
|
services.jellyfin = {
|
|
enable = true;
|
|
port = 8096;
|
|
reverseProxy.enable = true;
|
|
};
|
|
};
|
|
```
|
|
|
|
See [Custom Modules](./modules/README.md) for the full list of available modules and options.
|
|
|
|
## Adding a New Service Module
|
|
|
|
1. **Create the module directory**:
|
|
```bash
|
|
mkdir -p modules/nixos/services/my-service
|
|
```
|
|
|
|
2. **Write `default.nix`** using the `mkModule` helper:
|
|
```nix
|
|
{ config, lib, namespace, pkgs, ... }:
|
|
let
|
|
name = "my-service";
|
|
nebulaConfig = lib.${namespace}.mkModule {
|
|
inherit config name;
|
|
description = "my service description";
|
|
options = { };
|
|
moduleConfig = {
|
|
services.my-service = {
|
|
enable = true;
|
|
port = config.${namespace}.services.${name}.port;
|
|
};
|
|
};
|
|
};
|
|
in
|
|
{ imports = [ nebulaConfig ]; }
|
|
```
|
|
|
|
3. **Enable it** in a system configuration:
|
|
```nix
|
|
mjallen.services.my-service = {
|
|
enable = true;
|
|
port = 1234;
|
|
};
|
|
```
|
|
|
|
## Adding a New Package
|
|
|
|
1. Create a directory under `packages/`:
|
|
```bash
|
|
mkdir packages/my-package
|
|
```
|
|
|
|
2. Write a `default.nix` that returns a derivation. The package will be available as `pkgs.mjallen.my-package` in all configurations.
|
|
|
|
## Secrets
|
|
|
|
See the [Secrets Management](../README.md#secrets-management) section of the root README for:
|
|
- How age keys are derived from SSH host keys
|
|
- Adding a new machine as a SOPS recipient
|
|
- Adding/editing secrets
|
|
- Generating Nebula VPN certificates
|