nix-config/docs/getting-started.md

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

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):

   nix run github:nix-community/disko -- --mode disko /path/to/disko-config.nix
   

3. Clone this repo into the target:

   mkdir -p /mnt/etc/nixos
   git clone <repo-url> /mnt/etc/nixos
   

4. Install:

   nixos-install --flake /mnt/etc/nixos#hostname
   

Option 2: Adding a new system configuration

1. Create the system directory under the appropriate architecture:

   mkdir -p systems/x86_64-linux/new-hostname
   

2. Write the configuration — at minimum a default.nix:

   { namespace, ... }:
   {
     mjallen = {
       sops.enable = true;
       network.hostName = "new-hostname";
       user.name = "admin";
     };
   }
   

3. Generate hardware configuration (on the target machine):

   nixos-generate-config --no-filesystems --dir systems/x86_64-linux/new-hostname/
   

4. Add SOPS secrets for the new host — see Secrets Management.

5. Build and switch:

   sudo nixos-rebuild switch --flake .#new-hostname
   

Day-to-Day Usage

Applying configuration changes

# 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

# 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

# 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):

mjallen = {
  desktop.gnome.enable = true;
  hardware.amd.enable = true;
  gaming.enable = true;

  services.jellyfin = {
    enable = true;
    port = 8096;
    reverseProxy.enable = true;
  };
};

See Custom Modules for the full list of available modules and options.

Adding a New Service Module

1. Create the module directory:

   mkdir -p modules/nixos/services/my-service
   

2. Write default.nix using the mkModule helper:

   { 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:

   mjallen.services.my-service = {
     enable = true;
     port   = 1234;
   };
   

Adding a New Package

1. Create a directory under packages/:

   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 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