> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/soriphoono/homelab/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Home Modules

> Essential Home Manager modules for system configuration

Core modules provide the foundational configuration for your home environment. These modules handle identity, secrets, shells, and essential tools.

## Git Configuration

The Git module manages your Git identity, signing configuration, and multi-identity workflows.

### Options

<ParamField path="core.git.userName" type="string" required>
  The Git username to use for commits.

  ```nix theme={null}
  core.git.userName = "john";
  ```
</ParamField>

<ParamField path="core.git.userEmail" type="string" required>
  The Git email address to use for commits.

  ```nix theme={null}
  core.git.userEmail = "john@gmail.com";
  ```
</ParamField>

<ParamField path="core.git.projectsDir" type="path" default="~/Documents/Projects">
  The directory where Git projects are stored. Used for multi-identity configuration.

  ```nix theme={null}
  core.git.projectsDir = "/run/media/john_doe/Projects";
  ```
</ParamField>

<ParamField path="core.git.extraIdentities" type="attrset" default="{}">
  Additional Git identities for different contexts (work, school, etc.). Each identity has its own signing key and is activated based on project directory.

  ```nix theme={null}
  core.git.extraIdentities = {
    work = {
      directory = "Work";
      name = "john_work";
      email = "john_work@company.com";
      signingKey = "ssh-ed25519 AAAA...";
    };
    school = {
      directory = "School";
      name = "john_school";
      email = "JohnDoe@university.edu";
      signingKey = "ssh-ed25519 AAAA...";
    };
  };
  ```

  Projects in `~/Documents/Projects/Work/` will automatically use the work identity.
</ParamField>

### Features

* **SSH Signing** - Commits are signed with SSH keys by default
* **Delta Integration** - Beautiful diff viewing with line numbers and side-by-side display
* **Smart Defaults** - Histogram diff algorithm, auto-setup remote, pull rebase
* **Conflict Resolution** - zdiff3 merge conflict style and rerere enabled
* **Multi-Identity Support** - Different identities per project directory

### Example Configuration

```nix theme={null}
core.git = {
  userName = "soriphoono";
  userEmail = "soriphoono@gmail.com";
  projectsDir = config.home.homeDirectory + "/Projects";
  
  extraIdentities.work = {
    directory = "Work";
    name = "soriphoono-work";
    email = "soriphoono@work.com";
    signingKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...";
  };
};
```

***

## GitOps

Automate Home Manager configuration updates by syncing from a Git repository on a schedule.

### Options

<ParamField path="core.gitops.enable" type="boolean" default="false">
  Enable Home Manager GitOps synchronization.

  ```nix theme={null}
  core.gitops.enable = true;
  ```
</ParamField>

<ParamField path="core.gitops.repo" type="string" required>
  Git repository URL to fetch updates from.

  ```nix theme={null}
  core.gitops.repo = "https://github.com/user/homelab.git";
  ```
</ParamField>

<ParamField path="core.gitops.branch" type="string" default="main">
  Branch to pull from.

  ```nix theme={null}
  core.gitops.branch = "production";
  ```
</ParamField>

<ParamField path="core.gitops.interval" type="string" default="15m">
  Interval between syncs (systemd timer format).

  ```nix theme={null}
  core.gitops.interval = "30m";
  ```
</ParamField>

### Behavior

When enabled, a systemd user timer runs every `interval` and:

1. Fetches latest changes from the Git repository
2. Performs a hard reset to `origin/<branch>`
3. Runs `nh home switch` to apply the configuration

The flake is expected to be located at `~/Documents/Projects/homelab`.

### Example

```nix theme={null}
core.gitops = {
  enable = true;
  repo = "git@github.com:myuser/homelab.git";
  branch = "main";
  interval = "10m";
};
```

***

## Secrets Management

Manage encrypted secrets using SOPS and age encryption.

### Options

<ParamField path="core.secrets.enable" type="boolean" default="false">
  Enable secrets management.

  ```nix theme={null}
  core.secrets.enable = true;
  ```
</ParamField>

<ParamField path="core.secrets.defaultSopsFile" type="path" required>
  Default SOPS file containing encrypted secrets.

  ```nix theme={null}
  core.secrets.defaultSopsFile = ./secrets.yaml;
  ```
</ParamField>

<ParamField path="core.secrets.ageKeyFile" type="path" default="~/.config/sops/age/keys.txt">
  Path to the age key file for decryption.

  On NixOS, this is automatically provisioned. On non-NixOS systems, you must ensure this file exists.

  ```nix theme={null}
  core.secrets.ageKeyFile = "${config.home.homeDirectory}/.config/sops/age/keys.txt";
  ```
</ParamField>

<ParamField path="core.secrets.environment.enable" type="boolean" default="false">
  Enable environment variable secrets in dotenv format.

  ```nix theme={null}
  core.secrets.environment.enable = true;
  ```
</ParamField>

<ParamField path="core.secrets.environment.sopsFile" type="path">
  SOPS file containing environment secrets.

  ```nix theme={null}
  core.secrets.environment.sopsFile = ./env-secrets.yaml;
  ```
</ParamField>

### Example

```nix theme={null}
core.secrets = {
  enable = true;
  defaultSopsFile = ./secrets.yaml;
  ageKeyFile = "${config.home.homeDirectory}/.config/sops/age/keys.txt";
};
```

***

## Shell Configuration

Configure Fish shell, Starship prompt, and Fastfetch system information display.

### Options

<ParamField path="core.shells.shellAliases" type="attrset" default="{}">
  Shell command aliases applied to all shells.

  ```nix theme={null}
  core.shells.shellAliases = {
    g = "git";
    k = "kubectl";
    ls = "eza";
  };
  ```
</ParamField>

<ParamField path="core.shells.sessionVariables" type="attrset" default="{}">
  Environment variables to set for the user.

  ```nix theme={null}
  core.shells.sessionVariables = {
    EDITOR = "nvim";
    VISUAL = "nvim";
  };
  ```
</ParamField>

<ParamField path="core.shells.fish.enable" type="boolean" default="false">
  Enable Fish shell configuration.

  ```nix theme={null}
  core.shells.fish.enable = true;
  ```
</ParamField>

<ParamField path="core.shells.fish.generateCompletions" type="boolean" default="false">
  Generate Fish shell completions.

  ```nix theme={null}
  core.shells.fish.generateCompletions = true;
  ```
</ParamField>

<ParamField path="core.shells.fish.shellInit" type="string" default="">
  Extra commands to run on Fish shell initialization.

  ```nix theme={null}
  core.shells.fish.shellInit = "fastfetch";
  ```
</ParamField>

### Included Tools

* **Fish Shell** - Modern, user-friendly shell with syntax highlighting
* **Starship** - Minimal, blazing-fast prompt with Git status and context
* **Fastfetch** - System information display with custom logo
* **Direnv** - Automatic environment loading for projects
* **Eza** - Modern `ls` replacement with Git integration
* **Btop** - System resource monitor

### Example

```nix theme={null}
core.shells = {
  fish.enable = true;
  
  shellAliases = {
    g = "git";
    gc = "git commit";
    gp = "git push";
  };
  
  sessionVariables = {
    EDITOR = "nvim";
  };
};
```

***

## SSH Management

Manage SSH keys, agent configuration, and integration with secrets.

### Options

<ParamField path="core.ssh.publicKey" type="string" default="null">
  Primary SSH public key for authentication and Git signing.

  ```nix theme={null}
  core.ssh.publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...";
  ```
</ParamField>

<ParamField path="core.ssh.extraSSHKeys" type="attrset" default="{}">
  Additional SSH keys for different contexts. The private keys are provisioned from secrets.

  ```nix theme={null}
  core.ssh.extraSSHKeys = {
    work = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...";
    school = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...";
  };
  ```
</ParamField>

### Features

* **Automatic Key Deployment** - Public keys deployed to `~/.ssh/`
* **Secrets Integration** - Private keys provisioned from SOPS secrets
* **SSH Agent** - Automatically started if not provided by the system
* **SSH Config Management** - Handles OpenSSH permission requirements
* **Multi-Key Support** - Multiple identity files for different services

### Example

```nix theme={null}
core = {
  secrets.enable = true;
  
  ssh = {
    publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ...";
    
    extraSSHKeys = {
      work = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID...";
    };
  };
};
```

Private keys should be stored in your secrets file:

```yaml theme={null}
ssh:
  primary_key: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----
  work_key: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----
```

***

## Health Checks

Validate environment configuration and warn about potential issues.

### Options

<ParamField path="core.checks.enable" type="boolean" default="true">
  Enable environment health checks.

  ```nix theme={null}
  core.checks.enable = true;
  ```
</ParamField>

<ParamField path="core.checks.checkAgeKey" type="boolean" default="true">
  Check if the age key file exists when secrets are enabled.

  ```nix theme={null}
  core.checks.checkAgeKey = true;
  ```
</ParamField>

### Checks Performed

* **Age Key Existence** - Warns if secrets are enabled but the age key file is missing
* **Git Configuration** - Ensures Git username and email are set

More checks may be added in future versions.

***

## Default Packages

Core modules automatically install essential utilities:

* **Compression** - p7zip, unrar
* **Fonts** - Carlito, Liberation, Nerd Fonts (Aurulent Sans Mono, Sauce Code Pro)
* **Home Manager** - Self-management and `nh` (Nix helper) for system operations

### NH Configuration

The `nh` tool is configured for convenient Nix operations:

```nix theme={null}
programs.nh = {
  enable = true;
  clean = {
    enable = true;
    extraArgs = "--keep-since 5d";
  };
};
```

This automatically cleans old generations older than 5 days.