---
slug: "nix-fred-drake"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/fred-drake/nix@main/README.md"
repo: "https://github.com/fred-drake/nix"
source_file: "README.md"
branch: "main"
---
# Nix Configuration for Homelab and Workstations

## Overview

This repository contains Nix configurations for managing both personal
workstations and homelab infrastructure. It serves as the single source of
truth for all system configurations, ensuring consistency, reproducibility,
and maintainability across all environments.

## System Architecture

### Dendritic Feature Pattern

The repository uses a **dendritic pattern** powered by flake-parts and
import-tree. Feature modules in `modules/features/` self-register into
deferred module containers (`my.modules.nixos`, `my.modules.darwin`,
`my.modules.home-manager`), which are then applied to the appropriate
systems automatically. Capability flags (`config.my.hasDesktop`,
`config.my.hasNvidia`, etc.) allow features to guard their configuration
with `mkIf`, so a single feature module works across all hosts.

### Workstations

- **macOS Workstations**: Managed via nix-darwin
  - `macbook-pro`
  - `laisas-mac-mini`

### Servers

- **Infrastructure Services** (Managed via Colmena):
  - `headscale`: VPN coordination
  - `ironforge`: Multi-service host (nixarr with jellyfin, jellyseerr,
    sonarr, radarr, prowlarr, sabnzbd, bazarr, lidarr)
  - `orgrimmar`: Multi-service host (gitea, woodpecker, paperless,
    calibre, resume)
  - `anton`: WSL NixOS on Windows laptop (gaming and AI processing)

## Project Structure

```
flake.nix                    # Entry point: flake-parts + import-tree
lib/
  mkPkgs.nix                # Centralized pkgs factory (all overlays, cudaSupport)
  my-options-module.nix      # Shared capability flags (hasDesktop, hasNvidia, etc.)
  nixos-infra.nix            # NixOS commonModules + deferredModule collection
  darwin-infra.nix           # Darwin commonModules + mkDarwinSystem builder
  mk-home-manager.nix        # Home Manager attrset builder
modules/
  features/                  # Cross-cutting dendritic features (flake-parts modules)
                             # hm-*, darwin-*, and NixOS features using deferredModules
  services/                  # Server service modules (NixOS, with inline secrets)
  hosts/                     # Host definitions (nixos.nix, darwin.nix)
  infra/                     # Flake-parts plumbing (colmena, devshell, pkgs, etc.)
  home-manager/              # HM feature implementations + host overrides
  darwin/                    # Darwin feature implementations + per-host dirs
  nixos/                     # NixOS per-host configs (thin)
colmena/                     # Colmena entry + hosts/, hetzner-common, wsl-common
apps/                        # Custom packages (claude-code, fetchers, etc.)
homefiles/                   # Raw dotfiles and config files
overlays/                    # Package overlays
```

### Layer Responsibilities

- **`modules/features/`** — Flake-parts modules that register deferred
  NixOS, Darwin, or Home Manager modules. Each feature is self-contained
  and guards on capability flags.
- **`modules/services/`** — NixOS service modules for servers. Each owns
  its sops.secrets inline and defines a complete service (nginx, containers,
  systemd units).
- **`modules/hosts/`** — Host definitions that map hostnames to their
  system type, capability flags, and per-host overrides.
- **`modules/infra/`** — Flake-parts plumbing: pkgs instantiation,
  devshell, colmena config, system builders.
- **`lib/`** — Pure helper functions: centralized pkgs factory, capability
  flag options, infrastructure builders.
- **`colmena/`** — Per-host deployment files plus shared config
  (hetzner-common, wsl-common).

## Network Overview

The infrastructure uses multiple VLANs for security and organization:

- **Administration (VLAN 1)**: Server management and monitoring
- **Services (VLAN 50)**: Public-facing services and applications
- **IoT (VLAN 40)**: Internet of Things devices (isolated)
- **Workstations (VLAN 30)**: User devices and workstations

## Prerequisites

1. **Nix** installed on your system (on macOS, use Lix — see Initial Setup)
2. **SSH Key** (`id_ed25519`) in your `~/.ssh` directory
3. **Git** for version control

> **Note**: Homebrew does not need to be installed manually — this flake
> manages it out of the box via `nix-homebrew`.

> **Note**: The `id_ed25519` key is used for personal secrets and must be
> properly secured with 600 permissions.

## Development Environment

This repository exposes a Nix devshell (defined in `shell.nix` and wired
into the flake via `modules/infra/devshell.nix` as `devShells.default`)
that contains all the libraries and helper scripts needed to work on
this repository.

### Features Provided by the devshell

- **Development Tools**: Includes tools like `colmena`, `just`,
  `alejandra`, `statix`, and other utilities
- **Helper Scripts**: Automated scripts for updating NPM packages,
  container digests, fetcher repos, and more
- **Consistent Environment**: Ensures all contributors have the same
  tooling and dependencies

### Entering the devshell

To enter the development environment:

```bash
cd ~/nix
nix develop
```

This will load all the tools and environment variables defined in
`shell.nix`. Once inside the environment, you can use the helper scripts
and tools without additional installation.

If you have [direnv](https://direnv.net/) installed and configured, the
development environment will be automatically activated when you enter the
repository directory (via the `use flake` directive in `.envrc`).

## Just Targets

This project uses `just` for task automation. Here are the available targets:

- `switch` - Switches the system to the current configuration
- `build` - Builds the system in its current form
- `update-all` - Updates everything (runs update, update-npm-packages,
  update-repos, update-container-digests, update-secrets, and
  update-claude)
- `update` - Updates input definitions from remote resources
- `update-npm-packages` - Updates NPM packages
- `update-repos` - Pulls the latest hashes and shas from the repos in
  `apps/fetcher/repos.toml`
- `update-container-digests` - Updates the SHA digests of container images
- `update-secrets` - Updates the secrets flake
- `update-claude` - Updates the Claude Code binary and pinned plugin repos
- `format` - Format all .nix files with alejandra
- `lint` - Linting for the project with statix
- `bootstrap-signing` - Import iOS code signing identity into the macOS
  login keychain (one-time per Darwin host)
- `colmena HOST` - Runs `colmena apply` on the specified host
- `colmena-age HOST` - Reports the age of nixpkgs on a remote colmena host

## Container Management

This project uses Podman for container runtime with the following practices:

- **Image Management**:
  - Images are pinned to specific digests for reproducibility
  - The `container-digest` tool generates Nix files with SHA256 hashes
  - Container updates are explicit and intentional

## Initial Setup

1. Install Nix (if not already installed):

   - **macOS**: Use Lix.

     ```bash
     curl -sSf -L https://install.lix.systems/lix | sh -s -- install
     ```

   - **NixOS / Linux**:

     ```bash
     sh <(curl -L https://nixos.org/nix/install)
     ```

2. Clone this repository:

   ```bash
   git clone https://github.com/fred-drake/nix ~/nix
   cd ~/nix
   ```

3. Build the flake for your system. This will take a while the first time.
   - Macbook Pro: `nix --extra-experimental-features "nix-command flakes" build .#darwinConfigurations.macbook-pro.system`

## Key Management

### Personal Key (`id_ed25519`)

- Used for personal secrets and configurations
- Applies to both workstations and servers
- Manages user-specific settings and access tokens

### Infrastructure Key

- Dedicated to server infrastructure
- Manages service credentials and system configurations
- Separate from personal keys for better security

## Development Practices

### Code Organization

- **Dendritic Pattern**: Features self-register via flake-parts deferred
  modules, so adding a feature to one platform does not require editing
  host definitions
- **Capability Flags**: Shared options (`config.my.hasDesktop`, etc.) let
  features guard their config with `mkIf`
- **Centralized Packages**: `lib/mkPkgs.nix` is the single source of
  truth for overlays and package sets
- **DRY Principle**: Common patterns are extracted into `lib/` helpers and
  shared service modules in `modules/services/`

### Nix Best Practices

- **Package References**: Use `outPath` for symlinks to package locations
- **VS Code Extensions**: Managed through Home Manager configuration
- **Remote Deployment**: Colmena is used for managing remote server
  configurations

## Getting Help

For assistance with Nix configurations:

- Use `nixos` MCP server for NixOS-specific functionality
- Use `context7` MCP server for general Nix syntax assistance

## Final Steps

### For macOS systems:
1. Run the initial switch into the flake. This will take a long while the
   first time. On a brand-new machine the `./result/...` path will not work
   yet, so use the full `sudo` invocation:
   `sudo ./result/sw/bin/darwin-rebuild switch --flake ~/nix#macbook-pro`

   > **Note**: On first run, installing the Homebrew casks may fail on
   > `facebook/fb/idb-companion` because Xcode is not installed yet. Xcode is
   > installed later in the process, so simply run the switch again once it
   > is present and the cask will install successfully.
2. Reboot the machine to ensure all Mac settings were applied.

### For NixOS systems:
1. Run the initial switch into the flake:
   `sudo nixos-rebuild switch --flake ~/nix`
2. Reboot if needed for hardware changes.

## Post-setup That Can't Be Automated Yet

1. Allow Apple Watch to unlock the computer or sudo:
   `Settings -> Touch ID & Password -> Use Apple Watch to unlock
   applications and your Mac`
2. Open Raycast and import configuration from iCloud Drive
3. Disable spotlight search:
   `Settings -> Keyboard shortcuts -> Disable Spotlight Search`. Raycast
   will now be the default search tool when hitting Cmd+Space.