fixes and docs
This commit is contained in:
mjallen18
189
lib/README.md
189
lib/README.md
@@ -4,41 +4,186 @@ Utility functions for the NixOS/nix-darwin configuration. Exposed via Snowfall L
|
||||
|
||||
## Directory Structure
|
||||
|
||||
- `default.nix`: Main entry point — exports `module`, `file`, and `versioning`
|
||||
- `module/`: Module creation helpers (`mkModule`, `mkOpt`, `mkBoolOpt`, etc.)
|
||||
- `file/`: File and path utilities
|
||||
- `versioning/`: Multi-source version pinning helpers (used by packages)
|
||||
- `default.nix` — Main entry point; exports `module`, `file`, and `versioning`
|
||||
- `module/` — Module creation helpers (`mkModule`, `mkContainerService`, `mkSopsEnvFile`, `mkOpt`, etc.)
|
||||
- `file/` — File and path utilities
|
||||
- `versioning/` — Multi-source version pinning helpers (used by packages)
|
||||
|
||||
---
|
||||
|
||||
## Module Utilities (`lib.mjallen.module`)
|
||||
|
||||
### `mkModule`
|
||||
|
||||
Creates a NixOS service module with a standard set of options. All config is gated behind `cfg.enable`.
|
||||
|
||||
```nix
|
||||
lib.mjallen.mkModule {
|
||||
config # NixOS config attrset (pass-through from module args)
|
||||
name # Service name — used for option path and systemd unit
|
||||
description # Text for mkEnableOption (defaults to name)
|
||||
options # Extra options merged into the submodule
|
||||
moduleConfig # NixOS config body (applied when cfg.enable = true)
|
||||
domain # Option namespace domain (default: "services")
|
||||
serviceName # Systemd service name (default: name)
|
||||
}
|
||||
```
|
||||
|
||||
**Standard options provided for free:**
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `enable` | bool | `false` | Enable/disable the service |
|
||||
| `port` | int | `80` | Service listen port |
|
||||
| `listenAddress` | str | `"0.0.0.0"` | Bind address |
|
||||
| `openFirewall` | bool | `true` | Open TCP+UDP firewall ports |
|
||||
| `configDir` | str | `/var/lib/<name>` | Config directory |
|
||||
| `dataDir` | str | `/var/lib/<name>/data` | Data directory |
|
||||
| `createUser` | bool | `false` | Create a dedicated system user |
|
||||
| `configureDb` | bool | `false` | Create a PostgreSQL database |
|
||||
| `environmentFile` | str\|null | `null` | Path to an env-file |
|
||||
| `extraEnvironment` | attrs | `{}` | Extra environment variables |
|
||||
| `hashedPassword` | str\|null | `null` | Hashed password for web auth |
|
||||
| `puid` / `pgid` | str | `"911"` / `"100"` | UID/GID for container services |
|
||||
| `timeZone` | str | `"UTC"` | Timezone for container services |
|
||||
| `redis.enable` | bool | `false` | Create a Redis instance for this service |
|
||||
| `redis.port` | int | `6379` | Redis port |
|
||||
| `reverseProxy.enable` | bool | `false` | Add a Caddy reverse proxy block |
|
||||
| `reverseProxy.subdomain` | str | `<name>` | Caddy subdomain |
|
||||
| `reverseProxy.domain` | str | `"mjallen.dev"` | Caddy base domain |
|
||||
| `reverseProxy.upstreamUrl` | str\|null | `null` | Override upstream URL |
|
||||
| `reverseProxy.extraCaddyConfig` | lines | `""` | Extra Caddyfile directives |
|
||||
|
||||
**Default behaviour when enabled:**
|
||||
|
||||
- Adds Caddy reverse proxy block (if `reverseProxy.enable = true`)
|
||||
- Opens firewall ports (if `openFirewall = true`)
|
||||
- Creates system user/group (if `createUser = true`)
|
||||
- Creates PostgreSQL database (if `configureDb = true`)
|
||||
- Creates Redis instance (if `redis.enable = true`)
|
||||
- Adds `RequiresMountsFor` systemd dependency for `configDir` and `dataDir`
|
||||
|
||||
---
|
||||
|
||||
### `mkContainerService`
|
||||
|
||||
Wraps `mkModule` for Podman/OCI container services. Generates the full container definition automatically.
|
||||
|
||||
```nix
|
||||
lib.mjallen.mkContainerService {
|
||||
config # NixOS config attrset
|
||||
name # Service/container name
|
||||
image # OCI image reference (e.g. "ghcr.io/example/app:latest")
|
||||
internalPort # Port the container listens on internally
|
||||
description # Human-readable description (defaults to name)
|
||||
options # Extra mkModule options
|
||||
volumes # Extra volume mount strings
|
||||
environment # Extra environment variables (merged with PUID/PGID/TZ)
|
||||
environmentFiles # List of env-file paths (e.g. SOPS template paths)
|
||||
extraOptions # Extra --opt strings for the container runtime
|
||||
devices # Device mappings
|
||||
extraConfig # Extra NixOS config merged into moduleConfig
|
||||
}
|
||||
```
|
||||
|
||||
The systemd service is named `podman-<name>`, and the port binding is `<cfg.port>:<internalPort>`.
|
||||
|
||||
---
|
||||
|
||||
### `mkSopsEnvFile`
|
||||
|
||||
Generates a SOPS secrets block and a SOPS template env-file in a single call. Useful for services that need secrets injected as environment variables.
|
||||
|
||||
```nix
|
||||
lib.mjallen.mkSopsEnvFile {
|
||||
secrets # attrset: sops-key → extra attrs (owner, group, etc.)
|
||||
name # Template file name, e.g. "myapp.env"
|
||||
content # Template body (use config.sops.placeholder."key")
|
||||
restartUnit # Systemd unit to restart when secrets change
|
||||
owner # File owner (default: "nix-apps")
|
||||
group # File group (default: "jallen-nas")
|
||||
mode # File permissions (default: "660")
|
||||
sopsFile # Default SOPS file for all secrets
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Option helpers
|
||||
|
||||
| Function | Signature | Description |
|
||||
|---|---|---|
|
||||
| `mkOpt` | `type → default → description → mkOption` | Standard option shorthand |
|
||||
| `mkOpt'` | `type → default → mkOption` | `mkOpt` without description |
|
||||
| `mkBoolOpt` | `default → description → mkOption` | Boolean option shorthand |
|
||||
| `mkBoolOpt'` | `default → mkOption` | Boolean option without description |
|
||||
| `mkReverseProxyOpt` | `name → attrset` | Standard Caddy reverse proxy sub-options |
|
||||
|
||||
---
|
||||
|
||||
### Convenience shorthands
|
||||
|
||||
| Value | Expands to |
|
||||
|---|---|
|
||||
| `enabled` | `{ enable = true; }` |
|
||||
| `disabled` | `{ enable = false; }` |
|
||||
|
||||
---
|
||||
|
||||
### Attribute utilities
|
||||
|
||||
| Function | Description |
|
||||
|---|---|
|
||||
| `mkModule` | Create a NixOS module with standard options (enable, port, reverseProxy, firewall, user, postgresql, redis) |
|
||||
| `mkOpt` | `type → default → description → mkOption` shorthand |
|
||||
| `mkOpt'` | `mkOpt` without description |
|
||||
| `mkBoolOpt` | Boolean `mkOpt` shorthand |
|
||||
| `mkBoolOpt'` | Boolean `mkOpt` without description |
|
||||
| `mkReverseProxyOpt` | Standard Caddy reverse proxy sub-options |
|
||||
| `enabled` | `{ enable = true; }` shorthand |
|
||||
| `disabled` | `{ enable = false; }` shorthand |
|
||||
| `capitalize` | Capitalise the first character of a string |
|
||||
| `boolToNum` | Convert a boolean to 0 or 1 |
|
||||
| `default-attrs` | Apply `lib.mkDefault` to every value in an attrset |
|
||||
| `force-attrs` | Apply `lib.mkForce` to every value in an attrset |
|
||||
| `nested-default-attrs` | Apply `default-attrs` one level deeper |
|
||||
| `nested-force-attrs` | Apply `force-attrs` one level deeper |
|
||||
| `enableForSystem` | Filter a module list to only those that match a given system string |
|
||||
|
||||
## File Utilities (`lib.mjallen.file`)
|
||||
---
|
||||
|
||||
### String utilities
|
||||
|
||||
| Function | Description |
|
||||
|---|---|
|
||||
| `getFile` | Resolve a path relative to the flake root |
|
||||
| `safeImport` | Import a Nix file with a fallback on error |
|
||||
| `scanDir` | Return a list of directory names under a path |
|
||||
| `importModulesRecursive` | Recursively discover and import all `default.nix` files under a directory |
|
||||
| `capitalize` | Capitalise the first character of a string |
|
||||
|
||||
---
|
||||
|
||||
### Boolean utilities
|
||||
|
||||
| Function | Description |
|
||||
|---|---|
|
||||
| `boolToNum` | `true → 1`, `false → 0` |
|
||||
|
||||
---
|
||||
|
||||
## Home Manager Utilities (`lib.mjallen.module`)
|
||||
|
||||
### `mkHomeModule`
|
||||
|
||||
Creates a Home Manager module with a standard `enable` option.
|
||||
|
||||
```nix
|
||||
lib.mjallen.mkHomeModule {
|
||||
config # HM config attrset
|
||||
domain # Option namespace domain, e.g. "programs" or "desktop"
|
||||
name # Module name, e.g. "btop"
|
||||
description # Text for mkEnableOption (defaults to name)
|
||||
options # Extra options merged into the submodule
|
||||
moduleConfig # HM config body (applied when cfg.enable = true)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Utilities (`lib.mjallen.file`)
|
||||
|
||||
Helpers for resolving paths relative to the flake root. Primarily used internally by modules and packages.
|
||||
|
||||
---
|
||||
|
||||
## Versioning Utilities (`lib.mjallen.versioning`)
|
||||
|
||||
Used by packages that track multiple upstream variants (e.g. `linux-rpi`, `proton-cachyos`).
|
||||
See `lib/versioning/default.nix` for the full API.
|
||||
Used by packages that track multiple upstream variants (e.g. `proton-cachyos`, `linux-rpi`). Reads a `version.json` file and resolves sources with optional variable substitution and per-variant overrides.
|
||||
|
||||
See `lib/versioning/default.nix` for the full API and `docs/version.schema.json` for the `version.json` schema.
|
||||
|
||||
Reference in New Issue
Block a user