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

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