00b858fbbe
- Add stt-ptt language support documentation - Add rofi-project-opener module documentation - Add rofi-project-opener package documentation - Update zellij-ps documentation - Update guides and reference patterns - Update AGENTS.md with latest commands
606 lines
10 KiB
Markdown
606 lines
10 KiB
Markdown
# Using Modules Guide
|
|
|
|
How to use NixOS and Home Manager modules from m3ta-nixpkgs.
|
|
|
|
## Overview
|
|
|
|
Modules in m3ta-nixpkgs provide reusable configuration for NixOS (system-level) and Home Manager (user-level) settings. All modules use the `m3ta.*` namespace.
|
|
|
|
## Module Organization
|
|
|
|
### NixOS Modules
|
|
|
|
Located in `modules/nixos/`:
|
|
|
|
```
|
|
modules/nixos/
|
|
├── default.nix # Aggregates all NixOS modules
|
|
├── ports.nix # Port management
|
|
└── mem0.nix # Mem0 REST API server
|
|
```
|
|
|
|
### Home Manager Modules
|
|
|
|
Located in `modules/home-manager/` with categories:
|
|
|
|
```
|
|
modules/home-manager/
|
|
├── default.nix # Aggregates all HM modules
|
|
├── ports.nix # Port management
|
|
├── cli/ # CLI tools
|
|
│ ├── default.nix # Aggregates CLI modules
|
|
│ └── zellij-ps.nix
|
|
└── coding/ # Development tools
|
|
├── default.nix # Aggregates coding modules
|
|
└── editors.nix
|
|
```
|
|
|
|
## Importing Modules
|
|
|
|
### NixOS Modules
|
|
|
|
#### Import All Modules
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.nixosModules.default
|
|
];
|
|
}
|
|
```
|
|
|
|
#### Import Specific Module
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.nixosModules.mem0
|
|
];
|
|
}
|
|
```
|
|
|
|
#### Import from Local Path
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
./modules/nixos/mem0.nix
|
|
];
|
|
}
|
|
```
|
|
|
|
### Home Manager Modules
|
|
|
|
#### Import All Modules
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.homeManagerModules.default
|
|
];
|
|
}
|
|
```
|
|
|
|
#### Import Specific Module
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.homeManagerModules.ports
|
|
];
|
|
}
|
|
```
|
|
|
|
#### Import Category
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
# Import all CLI modules
|
|
m3ta-nixpkgs.homeManagerModules.cli.zellij-ps
|
|
];
|
|
}
|
|
```
|
|
|
|
## Available Modules
|
|
|
|
### NixOS Modules
|
|
|
|
#### `m3ta.ports`
|
|
|
|
Port management across hosts.
|
|
|
|
```nix
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {
|
|
nginx = 80;
|
|
grafana = 3000;
|
|
};
|
|
hostOverrides.laptop = {
|
|
nginx = 8080;
|
|
};
|
|
currentHost = config.networking.hostName;
|
|
};
|
|
```
|
|
|
|
**Documentation**: [Port Management Guide](./port-management.md)
|
|
|
|
#### `m3ta.mem0`
|
|
|
|
Mem0 REST API server for AI memory.
|
|
|
|
```nix
|
|
m3ta.mem0 = {
|
|
enable = true;
|
|
port = 8000;
|
|
llm = {
|
|
provider = "openai";
|
|
apiKeyFile = "/run/secrets/openai-api-key";
|
|
model = "gpt-4o-mini";
|
|
};
|
|
vectorStore = {
|
|
provider = "qdrant";
|
|
config = {
|
|
host = "localhost";
|
|
port = 6333;
|
|
};
|
|
};
|
|
};
|
|
```
|
|
|
|
**Documentation**: [mem0 Module](../modules/nixos/mem0.md)
|
|
|
|
### Home Manager Modules
|
|
|
|
#### `m3ta.ports`
|
|
|
|
Port management (similar to NixOS, with `generateEnvVars`).
|
|
|
|
```nix
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {
|
|
dev-server = 3000;
|
|
};
|
|
generateEnvVars = true;
|
|
currentHost = config.networking.hostName;
|
|
};
|
|
```
|
|
|
|
**Documentation**: [Port Management Guide](./port-management.md)
|
|
|
|
#### `cli.zellij-ps`
|
|
|
|
Zellij project switcher for quickly navigating between project folders.
|
|
|
|
```nix
|
|
cli.zellij-ps = {
|
|
enable = true;
|
|
package = pkgs.zellij-ps;
|
|
};
|
|
```
|
|
|
|
**Documentation**: [zellij-ps Module](../modules/home-manager/cli/zellij-ps.md)
|
|
|
|
#### `coding.editors`
|
|
|
|
Editor configurations.
|
|
|
|
```nix
|
|
m3ta.coding.editors = {
|
|
enable = true;
|
|
neovim.enable = true;
|
|
zed.enable = true;
|
|
};
|
|
```
|
|
|
|
**Documentation**: [Editors Module](../modules/home-manager/coding/editors.md)
|
|
|
|
## Common Patterns
|
|
|
|
### Module Configuration
|
|
|
|
All modules follow this pattern:
|
|
|
|
```nix
|
|
{ config, lib, pkgs, ... }:
|
|
with lib; let
|
|
cfg = config.m3ta.myModule;
|
|
in {
|
|
options.m3ta.myModule = {
|
|
enable = mkEnableOption "description";
|
|
# ... other options
|
|
};
|
|
|
|
config = mkIf cfg.enable {
|
|
# ... configuration
|
|
};
|
|
}
|
|
```
|
|
|
|
### Conditional Configuration
|
|
|
|
Use `mkIf` to conditionally apply config:
|
|
|
|
```nix
|
|
config = mkIf cfg.enable {
|
|
# Only applied when cfg.enable = true
|
|
services.my-service = {
|
|
enable = true;
|
|
};
|
|
}
|
|
```
|
|
|
|
### Multiple Conditions
|
|
|
|
Use `mkMerge` for multiple conditions:
|
|
|
|
```nix
|
|
config = mkMerge [
|
|
(mkIf cfg.feature1.enable {
|
|
# Applied when feature1 is enabled
|
|
})
|
|
(mkIf cfg.feature2.enable {
|
|
# Applied when feature2 is enabled
|
|
})
|
|
];
|
|
```
|
|
|
|
### Optional Dependencies
|
|
|
|
```nix
|
|
options.m3ta.myModule = {
|
|
enable = mkEnableOption "my module";
|
|
package = mkOption {
|
|
type = types.package;
|
|
default = pkgs.defaultPackage;
|
|
};
|
|
};
|
|
|
|
config = mkIf cfg.enable {
|
|
services.my-service = {
|
|
package = cfg.package;
|
|
};
|
|
};
|
|
```
|
|
|
|
## Configuration Examples
|
|
|
|
### Minimal NixOS Configuration
|
|
|
|
```nix
|
|
{pkgs, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.nixosModules.default
|
|
];
|
|
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {
|
|
my-service = 8080;
|
|
};
|
|
currentHost = "laptop";
|
|
};
|
|
|
|
services.my-custom-service = {
|
|
enable = true;
|
|
port = config.m3ta.ports.get "my-service";
|
|
};
|
|
}
|
|
```
|
|
|
|
### Full NixOS Configuration
|
|
|
|
```nix
|
|
{config, pkgs, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.nixosModules.default
|
|
];
|
|
|
|
# Port management
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {
|
|
nginx = 80;
|
|
grafana = 3000;
|
|
prometheus = 9090;
|
|
mem0 = 8000;
|
|
};
|
|
hostOverrides.laptop = {
|
|
nginx = 8080;
|
|
mem0 = 8081;
|
|
};
|
|
currentHost = config.networking.hostName;
|
|
};
|
|
|
|
# Mem0 service
|
|
m3ta.mem0 = {
|
|
enable = true;
|
|
port = config.m3ta.ports.get "mem0";
|
|
llm = {
|
|
provider = "openai";
|
|
apiKeyFile = "/run/secrets/openai-api-key";
|
|
};
|
|
vectorStore = {
|
|
provider = "qdrant";
|
|
config = {
|
|
host = "localhost";
|
|
port = 6333;
|
|
};
|
|
};
|
|
};
|
|
|
|
# Nginx
|
|
services.nginx = {
|
|
enable = true;
|
|
httpConfig = ''
|
|
server {
|
|
listen ${toString (config.m3ta.ports.get "nginx")};
|
|
root /var/www;
|
|
}
|
|
'';
|
|
};
|
|
|
|
# Grafana
|
|
services.grafana = {
|
|
enable = true;
|
|
settings.server.http_port = config.m3ta.ports.get "grafana";
|
|
};
|
|
}
|
|
```
|
|
|
|
### Minimal Home Manager Configuration
|
|
|
|
```nix
|
|
{pkgs, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.homeManagerModules.default
|
|
];
|
|
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {
|
|
dev-server = 3000;
|
|
};
|
|
currentHost = "desktop";
|
|
};
|
|
|
|
home.sessionVariables = {
|
|
DEV_PORT = toString (config.m3ta.ports.get "dev-server");
|
|
};
|
|
}
|
|
```
|
|
|
|
### Full Home Manager Configuration
|
|
|
|
```nix
|
|
{config, pkgs, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.homeManagerModules.default
|
|
];
|
|
|
|
# Port management
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {
|
|
dev-server = 3000;
|
|
nextjs = 3001;
|
|
vite = 5173;
|
|
};
|
|
hostOverrides.laptop = {
|
|
vite = 5174;
|
|
};
|
|
currentHost = config.networking.hostName;
|
|
};
|
|
|
|
# CLI tools
|
|
cli.zellij-ps = {
|
|
enable = true;
|
|
};
|
|
|
|
# Coding tools
|
|
coding.editors = {
|
|
enable = true;
|
|
neovim.enable = true;
|
|
};
|
|
|
|
# Packages
|
|
home.packages = with pkgs; [
|
|
code2prompt
|
|
zellij-ps
|
|
];
|
|
|
|
# Environment variables
|
|
home.sessionVariables = {
|
|
EDITOR = "nvim";
|
|
DEV_SERVER_PORT = toString (config.m3ta.ports.get "dev-server");
|
|
};
|
|
}
|
|
```
|
|
|
|
## Module Options Reference
|
|
|
|
### Standard Options
|
|
|
|
All modules typically include:
|
|
|
|
| Option | Type | Description |
|
|
|---------|-------|-------------|
|
|
| `enable` | `boolean` | Enable the module |
|
|
| `package` | `package` | Custom package to use |
|
|
| `extraConfig` | `attrs` | Additional configuration |
|
|
|
|
### Port Management Options
|
|
|
|
| Option | Type | Description |
|
|
|---------|-------|-------------|
|
|
| `definitions` | `attrsOf int` | Default port definitions |
|
|
| `hostOverrides` | `attrsOf attrs` | Host-specific overrides |
|
|
| `currentHost` | `string` | Current hostname |
|
|
| `generateEnvVars` | `boolean` | Generate environment variables (HM only) |
|
|
|
|
## Combining with Other Flakes
|
|
|
|
### Using Multiple Module Sources
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
# m3ta-nixpkgs modules
|
|
m3ta-nixpkgs.nixosModules.default
|
|
|
|
# Other flake modules
|
|
inputs.impermanence.nixosModules.impermanence
|
|
inputs.sops-nix.nixosModules.sops
|
|
];
|
|
|
|
# Configure all modules
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {nginx = 80;};
|
|
currentHost = config.networking.hostName;
|
|
};
|
|
|
|
environment.persistence = {
|
|
"/persist" = {
|
|
directories = ["/var/lib/mem0"];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
### Using with Secrets
|
|
|
|
```nix
|
|
{config, ...}: {
|
|
imports = [
|
|
m3ta-nixpkgs.nixosModules.default
|
|
inputs.sops-nix.nixosModules.sops
|
|
];
|
|
|
|
sops.secrets = {
|
|
openai-api-key = {};
|
|
};
|
|
|
|
m3ta.mem0 = {
|
|
enable = true;
|
|
llm = {
|
|
apiKeyFile = config.sops.secrets.openai-api-key.path;
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Module Not Found
|
|
|
|
Error: `error: The option 'm3ta.mymodule' does not exist`
|
|
|
|
**Solutions**:
|
|
1. Make sure you imported the module:
|
|
|
|
```nix
|
|
imports = [
|
|
m3ta-nixpkgs.nixosModules.default
|
|
];
|
|
```
|
|
|
|
2. Check module name is correct
|
|
|
|
```nix
|
|
# Correct
|
|
m3ta.mem0.enable = true;
|
|
|
|
# Wrong
|
|
m3ta.mymodule.enable = true; # Doesn't exist
|
|
```
|
|
|
|
### Option Type Mismatch
|
|
|
|
Error: `type mismatch at 'm3ta.mymodule.enable', expected a boolean but got a list`
|
|
|
|
**Solution**: Check option types in documentation
|
|
|
|
```nix
|
|
# Correct
|
|
m3ta.mymodule.enable = true;
|
|
|
|
# Wrong
|
|
m3ta.mymodule.enable = [true]; # Should be boolean
|
|
```
|
|
|
|
### Port Not Defined
|
|
|
|
Error: `Service "foo" not defined`
|
|
|
|
**Solution**: Add to port definitions
|
|
|
|
```nix
|
|
m3ta.ports = {
|
|
definitions = {
|
|
foo = 8080; # Add this
|
|
};
|
|
};
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Use Namespaces
|
|
|
|
Always use the `m3ta.*` namespace:
|
|
|
|
```nix
|
|
# Good
|
|
m3ta.mem0.enable = true;
|
|
|
|
# Bad (potential conflicts)
|
|
mem0.enable = true;
|
|
```
|
|
|
|
### Document Your Configuration
|
|
|
|
Add comments explaining module usage:
|
|
|
|
```nix
|
|
# Port management for multi-host setup
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = {
|
|
nginx = 80;
|
|
grafana = 3000;
|
|
};
|
|
hostOverrides.laptop = {
|
|
nginx = 8080; # Use different port on laptop
|
|
};
|
|
currentHost = config.networking.hostName;
|
|
};
|
|
|
|
# Mem0 AI memory service
|
|
m3ta.mem0 = {
|
|
enable = true;
|
|
port = config.m3ta.ports.get "mem0";
|
|
};
|
|
```
|
|
|
|
### Test Configuration
|
|
|
|
```bash
|
|
# Test NixOS configuration without applying
|
|
sudo nixos-rebuild test --flake .#hostname
|
|
|
|
# Check configuration
|
|
nix flake check
|
|
|
|
# Show all options
|
|
nix eval .#nixosConfigurations.hostname.config.m3ta --apply builtins.attrNames
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [Port Management](./port-management.md) - Detailed port management guide
|
|
- [Adding Packages](./adding-packages.md) - How to add new packages
|
|
- [Architecture](../ARCHITECTURE.md) - Understanding module structure
|
|
- [Contributing](../CONTRIBUTING.md) - Code style and guidelines
|