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 access to the machine you want to configure

Initial Setup

1. Cloning the Repository

Clone this repository to your local machine:

git clone ssh://nix-apps@localhost:2222/mjallen/nix-config.git
cd nix-config

2. Setting Up a New System

Option 1: Using an Existing Configuration

If you're setting up a new machine that should be identical to an existing configuration:

1. Boot from a NixOS installation media
2. Mount your target partitions to /mnt
3. Clone this repository:

   nixos-enter
   cd /mnt
   mkdir -p /mnt/etc/nixos
   git clone ssh://nix-apps@localhost:2222/mjallen/nix-config.git /mnt/etc/nixos
   

4. Install NixOS with the desired system profile:

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

   Replace hostname with the target system name (e.g., matt-nixos, jallen-nas, etc.)

Option 2: Creating a New System Configuration

If you're adding a completely new system:

1. Create a new directory for your system configuration:

   mkdir -p systems/$(uname -m)-linux/new-hostname
   

2. Create the basic configuration files:

   cat > systems/$(uname -m)-linux/new-hostname/default.nix << EOF
   { lib, pkgs, ... }:
   {
     imports = [
       ./hardware-configuration.nix
       # Add other needed module imports here
     ];
   
     networking.hostName = "new-hostname";
   
     # Add your system-specific configuration here
   }
   EOF
   

3. Generate the hardware configuration:

   nixos-generate-config --no-filesystems --dir systems/$(uname -m)-linux/new-hostname/
   

4. Add your new system to the flake by adding it to the hosts section in flake.nix

5. Build and install the configuration:

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

Secret Management

Setting Up Sops-Nix

1. Create a GPG key if you don't already have one:

   gpg --full-generate-key
   

2. Add your key to .sops.yaml:

   # Get your key fingerprint
   gpg --list-secret-keys --keyid-format=long
   
   # Edit the .sops.yaml file to add your key
   

3. Create a new encrypted secret:

   sops secrets/newsecret.yaml
   

Common Tasks

Updating the Repository

git pull
sudo nixos-rebuild switch --flake .#hostname

Adding a New Package

1. For standard packages, add them to your system or home configuration:

   environment.systemPackages = with pkgs; [
     new-package
   ];
   

2. For custom packages, add them to the packages directory:

   mkdir -p packages/new-package
   # Create the necessary Nix files
   

Adding a New Module

1. Create a new module directory:

   mkdir -p modules/nixos/new-module
   

2. Create the module files:

   # Create options.nix
   cat > modules/nixos/new-module/options.nix << EOF
   { lib, namespace, ... }:
   with lib;
   {
     options.${namespace}.new-module = {
       enable = mkEnableOption "Enable new module";
       # Add other options here
     };
   }
   EOF
   
   # Create default.nix
   cat > modules/nixos/new-module/default.nix << EOF
   { config, lib, namespace, ... }:
   let
     cfg = config.${namespace}.new-module;
   in
   {
     imports = [ ./options.nix ];
   
     config = lib.mkIf cfg.enable {
       # Add your configuration here
     };
   }
   EOF
   

3. Import your module in your system configuration:

   imports = [
     # ...
     ../../../modules/nixos/new-module
   ];
   
   ${namespace}.new-module.enable = true;