fixes and docs
This commit is contained in:
mjallen18
@@ -2,115 +2,294 @@
|
||||
|
||||
This directory contains documentation for the custom modules used in this NixOS configuration.
|
||||
|
||||
## Module Types
|
||||
## Overview
|
||||
|
||||
The repository uses two main types of modules:
|
||||
Modules are split into three categories:
|
||||
|
||||
1. **NixOS Modules** - System-level configurations in `modules/nixos/`
|
||||
2. **Home Manager Modules** - User-level configurations in `modules/home/`
|
||||
- **NixOS modules** (`modules/nixos/`) — system-level configuration
|
||||
- **Home Manager modules** (`modules/home/`) — user-level configuration
|
||||
- **Darwin modules** (`modules/darwin/`) — macOS-specific configuration
|
||||
|
||||
All modules are auto-discovered by Snowfall Lib and expose options under the `mjallen` namespace.
|
||||
|
||||
## NixOS Modules
|
||||
|
||||
These modules configure the system-level aspects of NixOS:
|
||||
### Boot (`modules/nixos/boot/`)
|
||||
|
||||
- [Boot Modules](./boot.md) - Boot loader and kernel configurations
|
||||
- [Desktop Modules](./desktop.md) - Desktop environment configurations
|
||||
- [Development Modules](./development.md) - Development tools and environments
|
||||
- [Hardware Modules](./hardware.md) - Hardware-specific configurations
|
||||
- [Home Assistant Modules](./homeassistant.md) - Home automation configuration
|
||||
- [Networking Modules](./network.md) - Network configuration and services
|
||||
- [Security Modules](./security.md) - Security-related configurations
|
||||
- [Services Modules](./services.md) - Various service configurations
|
||||
- [System Modules](./system.md) - General system configurations
|
||||
- [Virtualization Modules](./virtualization.md) - Virtualization and containerization
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| `boot/common/` | Shared boot defaults (quiet boot, Plymouth) |
|
||||
| `boot/lanzaboote/` | Secure Boot via Lanzaboote |
|
||||
| `boot/systemd-boot/` | systemd-boot (non-secure-boot systems) |
|
||||
| `boot/plymouth/` | Plymouth splash screen |
|
||||
|
||||
### Desktop (`modules/nixos/desktop/`)
|
||||
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| `desktop/gnome/` | GNOME desktop environment |
|
||||
| `desktop/hyprland/` | Hyprland compositor |
|
||||
| `desktop/cosmic/` | COSMIC desktop environment |
|
||||
|
||||
### Development (`modules/nixos/development/`)
|
||||
|
||||
Enables development tools and language support. Options:
|
||||
|
||||
```nix
|
||||
mjallen.development = {
|
||||
enable = true;
|
||||
includeLanguages = [ "python" "c" ];
|
||||
includeContainers = true;
|
||||
};
|
||||
```
|
||||
|
||||
### Hardware (`modules/nixos/hardware/`)
|
||||
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| `hardware/amd/` | AMD GPU (AMDGPU driver, LACT) |
|
||||
| `hardware/nvidia/` | NVIDIA GPU |
|
||||
| `hardware/battery/` | Battery charge threshold management |
|
||||
| `hardware/raspberry-pi/` | Raspberry Pi hardware support and DT overlays |
|
||||
| `hardware/openrgb/` | OpenRGB for LED control |
|
||||
| `hardware/btrfs/` | btrfs-specific settings |
|
||||
| `hardware/common/` | Common hardware defaults |
|
||||
|
||||
### Headless (`modules/nixos/headless/`)
|
||||
|
||||
Server profile — disables suspend/hibernate, enables systemd watchdog, no display manager.
|
||||
|
||||
```nix
|
||||
mjallen.headless.enable = true;
|
||||
```
|
||||
|
||||
### Home Assistant (`modules/nixos/homeassistant/`)
|
||||
|
||||
Full smart home stack. See [Home Assistant docs](../home-assistant/README.md) for details.
|
||||
|
||||
```nix
|
||||
mjallen.services.home-assistant.enable = true;
|
||||
```
|
||||
|
||||
### Impermanence (`modules/nixos/impermanence/`)
|
||||
|
||||
Ephemeral root filesystem with explicit persistence declarations.
|
||||
|
||||
```nix
|
||||
mjallen.impermanence = {
|
||||
enable = true;
|
||||
extraDirectories = [ { directory = "/var/lib/myapp"; user = "myapp"; } ];
|
||||
};
|
||||
```
|
||||
|
||||
### Monitoring (`modules/nixos/monitoring/`)
|
||||
|
||||
Prometheus metrics and Grafana dashboards.
|
||||
|
||||
```nix
|
||||
mjallen.monitoring.enable = true;
|
||||
```
|
||||
|
||||
### Network (`modules/nixos/network/`)
|
||||
|
||||
Hostname, firewall, NetworkManager profiles, static IP configuration.
|
||||
|
||||
```nix
|
||||
mjallen.network = {
|
||||
hostName = "my-host";
|
||||
ipv4 = {
|
||||
method = "manual";
|
||||
address = "10.0.1.5/24";
|
||||
gateway = "10.0.1.1";
|
||||
dns = "1.1.1.1";
|
||||
interface = "eth0";
|
||||
};
|
||||
firewall = {
|
||||
enable = true;
|
||||
allowedTCPPorts = [ 80 443 ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Power (`modules/nixos/power/`)
|
||||
|
||||
UPS (NUT) support.
|
||||
|
||||
```nix
|
||||
mjallen.power.ups.enable = true;
|
||||
```
|
||||
|
||||
### Security (`modules/nixos/security/`)
|
||||
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| `security/common/` | Common hardening (kernel params, etc.) |
|
||||
| `security/tpm/` | TPM2 — Clevis disk unlock |
|
||||
|
||||
### Services (`modules/nixos/services/`)
|
||||
|
||||
~50 self-hosted service modules, all built with `mkModule`. Each exposes at minimum `enable`, `port`, `reverseProxy`, and `openFirewall`. Common usage pattern:
|
||||
|
||||
```nix
|
||||
mjallen.services.jellyfin = {
|
||||
enable = true;
|
||||
port = 8096;
|
||||
reverseProxy.enable = true;
|
||||
};
|
||||
```
|
||||
|
||||
Available services:
|
||||
|
||||
`actual`, `ai`, `appimage`, `arrs`, `attic`, `authentik`, `authentikRac`, `booklore`, `caddy`, `calibre`, `calibre-web`, `cockpit`, `code-server`, `collabora`, `coturn`, `crowdsec`, `dispatcharr`, `free-games-claimer`, `gitea`, `glance`, `glances`, `grafana`, `guacd`, `headscale`, `immich`, `jellyfin`, `jellyseerr`, `lubelogger`, `manyfold`, `matrix`, `minecraft`, `mongodb`, `nebula`, `netbootxyz`, `nextcloud`, `ntfy`, `onlyoffice`, `opencloud`, `orca`, `paperless`, `paperless-ai`, `protonmail-bridge`, `restic`, `samba`, `sparky-fitness`, `sparky-fitness-server`, `sunshine`, `tdarr`, `termix`, `tunarr`, `unmanic`, `uptime-kuma`, `wyoming`, `your-spotify`
|
||||
|
||||
#### Nebula VPN (`services/nebula/`)
|
||||
|
||||
Unified module for both lighthouse and node roles:
|
||||
|
||||
```nix
|
||||
# Lighthouse
|
||||
mjallen.services.nebula = {
|
||||
enable = true;
|
||||
isLighthouse = true;
|
||||
port = 4242;
|
||||
secretsPrefix = "pi5/nebula";
|
||||
secretsFile = lib.snowfall.fs.get-file "secrets/pi5-secrets.yaml";
|
||||
hostSecretName = "lighthouse";
|
||||
};
|
||||
|
||||
# Node
|
||||
mjallen.services.nebula = {
|
||||
enable = true;
|
||||
port = 4242;
|
||||
lighthouses = [ "10.1.1.1" ];
|
||||
staticHostMap = { "10.1.1.1" = [ "mjallen.dev:4242" ]; };
|
||||
secretsPrefix = "mymachine/nebula";
|
||||
secretsFile = lib.snowfall.fs.get-file "secrets/mymachine-secrets.yaml";
|
||||
hostSecretName = "mymachine";
|
||||
};
|
||||
```
|
||||
|
||||
See [Secrets Management](../../README.md#generating-nebula-vpn-certificates) for how to generate the required certificates.
|
||||
|
||||
### SOPS (`modules/nixos/sops/`)
|
||||
|
||||
Configures sops-nix to decrypt secrets using the machine's SSH host key as an age key.
|
||||
|
||||
```nix
|
||||
mjallen.sops = {
|
||||
enable = true;
|
||||
sshKeyPaths = [ "/etc/ssh/ssh_host_ed25519_key" ]; # default
|
||||
};
|
||||
```
|
||||
|
||||
### User (`modules/nixos/user/`)
|
||||
|
||||
System user account management.
|
||||
|
||||
```nix
|
||||
mjallen.user = {
|
||||
name = "matt";
|
||||
mutableUsers = false;
|
||||
extraGroups = [ "docker" "video" ];
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Home Manager Modules
|
||||
|
||||
These modules configure user environments:
|
||||
### Desktop
|
||||
|
||||
- [Applications](./home/applications.md) - User applications
|
||||
- [Desktop](./home/desktop.md) - User desktop environments
|
||||
- [Development](./home/development.md) - User development environments
|
||||
- [Media](./home/media.md) - Media applications
|
||||
- [Shell](./home/shell.md) - Shell configurations
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| `desktop/gnome/` | GNOME user settings (extensions, keybindings, etc.) |
|
||||
| `desktop/theme/` | Theme configuration |
|
||||
|
||||
## Module Structure
|
||||
### Programs
|
||||
|
||||
Each module follows a standard structure:
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| `programs/btop/` | btop system monitor |
|
||||
| `programs/code/` | VS Code / VSCodium settings |
|
||||
| `programs/git/` | Git user config |
|
||||
| `programs/hyprland/` | Hyprland compositor config |
|
||||
| `programs/kitty/` | Kitty terminal config |
|
||||
| `programs/librewolf/` | LibreWolf browser settings |
|
||||
| `programs/mako/` | Mako notification daemon |
|
||||
| `programs/nwg-dock/` | nwg-dock panel |
|
||||
| `programs/nwg-drawer/` | nwg-drawer app launcher |
|
||||
| `programs/nwg-panel/` | nwg-panel bar |
|
||||
| `programs/opencode/` | OpenCode AI coding assistant |
|
||||
| `programs/update-checker/` | Automatic flake update checker |
|
||||
| `programs/waybar/` | Waybar status bar |
|
||||
| `programs/wlogout/` | Logout menu |
|
||||
| `programs/wofi/` | Wofi launcher |
|
||||
| `programs/zsh/` | Zsh shell config |
|
||||
|
||||
```
|
||||
modules/nixos/example-module/
|
||||
├── default.nix # Main implementation
|
||||
├── options.nix # Option declarations
|
||||
└── submodule/ # Optional submodules
|
||||
└── default.nix # Submodule implementation
|
||||
```
|
||||
### Other
|
||||
|
||||
### default.nix
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| `gpg/` | GPG agent configuration |
|
||||
| `services/pass/` | Password store |
|
||||
| `shell-aliases/` | Common shell aliases |
|
||||
| `sops/` | User-level SOPS secrets |
|
||||
| `stylix/` | System-wide theming (colours, fonts, wallpaper) |
|
||||
| `user/` | User environment defaults |
|
||||
|
||||
The `default.nix` file contains the main implementation of the module:
|
||||
---
|
||||
|
||||
## Module Development
|
||||
|
||||
### Using `mkModule`
|
||||
|
||||
The `lib.mjallen.mkModule` helper (`lib/module/default.nix`) creates a fully-featured NixOS module from a minimal spec:
|
||||
|
||||
```nix
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
pkgs,
|
||||
namespace,
|
||||
...
|
||||
}:
|
||||
{ config, lib, namespace, pkgs, ... }:
|
||||
let
|
||||
cfg = config.${namespace}.example-module;
|
||||
in
|
||||
{
|
||||
imports = [ ./options.nix ];
|
||||
name = "my-service";
|
||||
cfg = config.${namespace}.services.${name};
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
# Module implementation when enabled
|
||||
serviceConfig = lib.${namespace}.mkModule {
|
||||
inherit config name;
|
||||
description = "my service";
|
||||
options = {
|
||||
# extra options beyond the standard set
|
||||
myOption = lib.${namespace}.mkOpt lib.types.str "default" "Description";
|
||||
};
|
||||
moduleConfig = {
|
||||
services.my-service = {
|
||||
enable = true;
|
||||
port = cfg.port;
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
in
|
||||
{ imports = [ serviceConfig ]; }
|
||||
```
|
||||
|
||||
### options.nix
|
||||
Standard options provided by `mkModule` for free: `enable`, `port`, `listenAddress`, `openFirewall`, `configDir`, `dataDir`, `createUser`, `configureDb`, `environmentFile`, `reverseProxy.*`, `redis.*`, `extraEnvironment`, `hashedPassword`, `puid`, `pgid`, `timeZone`.
|
||||
|
||||
The `options.nix` file declares the module's configuration options:
|
||||
### Using `mkContainerService`
|
||||
|
||||
For Podman/OCI container services, use `mkContainerService` instead:
|
||||
|
||||
```nix
|
||||
{ lib, namespace, ... }:
|
||||
with lib;
|
||||
let
|
||||
inherit (lib.${namespace}) mkOpt;
|
||||
in
|
||||
{
|
||||
options.${namespace}.example-module = {
|
||||
enable = mkEnableOption "enable example module";
|
||||
# Other option declarations
|
||||
};
|
||||
}
|
||||
lib.${namespace}.mkContainerService {
|
||||
inherit config name;
|
||||
image = "ghcr.io/example/my-app:latest";
|
||||
internalPort = 8080;
|
||||
volumes = [ "${cfg.configDir}:/config" ];
|
||||
};
|
||||
```
|
||||
|
||||
## Using Modules
|
||||
|
||||
To use a module in your system configuration:
|
||||
|
||||
1. Enable the module in your system configuration:
|
||||
### Option helpers
|
||||
|
||||
```nix
|
||||
{ config, ... }:
|
||||
{
|
||||
mjallen.example-module = {
|
||||
enable = true;
|
||||
# Other options
|
||||
};
|
||||
}
|
||||
lib.mjallen.mkOpt types.str "default" "description"
|
||||
lib.mjallen.mkBoolOpt false "description"
|
||||
lib.mjallen.mkOpt' types.int 80 # no description
|
||||
lib.mjallen.enabled # { enable = true; }
|
||||
lib.mjallen.disabled # { enable = false; }
|
||||
```
|
||||
|
||||
## Creating New Modules
|
||||
|
||||
To create a new module:
|
||||
|
||||
1. Create a new directory in `modules/nixos/` or `modules/home/`
|
||||
2. Create `default.nix` and `options.nix` files
|
||||
3. Implement your module functionality
|
||||
4. Import the module in your system configuration
|
||||
|
||||
See the [Getting Started](../getting-started.md) guide for more details on creating modules.
|
||||
Reference in New Issue
Block a user