m3tam3re/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add hierarchical AGENTS.md knowledge base

Browse Source 
- Update root AGENTS.md with regenerative content (144 lines, telegraphic)
- Add pkgs/AGENTS.md for package registry conventions (33 lines)
- Add docs/AGENTS.md for documentation structure (34 lines)
- All files follow telegraphic style, no redundancy with parent
- Preserves existing modules/home-manager/AGENTS.md

Hierarchy:
  ./AGENTS.md (root)
  ├── pkgs/AGENTS.md
  ├── docs/AGENTS.md
  └── modules/home-manager/AGENTS.md (existing)
This commit is contained in:
m3tm3re
2025-12-30 15:02:58 +01:00
parent c5e161026d
commit 824ad97ef9
12 changed files with 863 additions and 1251 deletions
Download Patch File Download Diff File Expand all files Collapse all files

491
README.md
View File

@@ -1,62 +1,30 @@
# m3ta-nixpkgs
My personal Nix repository containing custom packages, overlays, NixOS modules, and Home Manager modules.
Personal Nix flake repository: custom packages, overlays, NixOS modules, and Home Manager modules.
## Features
- 🎁 **Custom Packages**: Collection of personal Nix packages
- 🔄 **Overlays**: Package modifications and enhancements
- 🐚 **Development Shells**: Pre-configured environments for Python and DevOps
- 🐚 **Development Shells**: Pre-configured environments (Python, DevOps)
- ⚙️ **NixOS Modules**: System-level configuration modules
- 🏠 **Home Manager Modules**: User-level configuration modules
- 📚 **Library Functions**: Helper utilities for configuration management
- ❄️ **Flakes Only**: Modern Nix flakes support (no channels)
## Repository Structure
## Quick Links
```
m3ta-nixpkgs/
├── flake.nix # Main flake configuration
├── pkgs/ # Custom packages
│ ├── default.nix # Package registry
│ ├── code2prompt/
│ ├── hyprpaper-random/
│ ├── launch-webapp/
│ ├── msty-studio/
│ ├── pomodoro-timer/
│ ├── tuxedo-backlight/
│ └── zellij-ps/
├── shells/ # Development shells
│ ├── default.nix # Shell registry (default, python, devops)
│ ├── python.nix # Python development environment
│ └── devops.nix # DevOps/infrastructure tools
├── overlays/ # Overlays
│ ├── default.nix
│ └── mods/ # Package modifications
│ ├── default.nix
│ └── n8n.nix
├── modules/
│ ├── nixos/ # NixOS modules
│ │ ├── default.nix
│ │ └── ports.nix # Port management module
│ └── home-manager/ # Home Manager modules
│ ├── default.nix
│ ├── ports.nix # Port management module
│ └── zellij-ps.nix
├── lib/ # Library functions
│ ├── default.nix # Library entry point
│ └── ports.nix # Port management utilities
├── examples/ # Usage examples
│ ├── home-manager-standalone.nix
│ ├── nixos-configuration.nix
└── templates/ # Templates for new packages/modules
```
- 📖 [Full Documentation](./docs)
- 🚀 [Quick Start Guide](./docs/QUICKSTART.md)
- 📚 [Architecture](./docs/ARCHITECTURE.md)
- 🤝 [Contributing](./docs/CONTRIBUTING.md)
- 📦 [Packages](./docs/packages/)
- ⚙️ [Modules](./docs/modules/)
- 📖 [Guides](./docs/guides/)
## Usage
## Installation
### Adding to Your Flake
Add this repository to your flake inputs:
### Add to Your Flake
```nix
{
@@ -67,446 +35,22 @@ Add this repository to your flake inputs:
}
```
### Using Packages in NixOS Configuration
#### Method 1: Using the Overlay
```nix
{
nixpkgs.overlays = [
inputs.m3ta-nixpkgs.overlays.default
];
environment.systemPackages = with pkgs; [
code2prompt
hyprpaper-random
msty-studio
# ... any other custom packages
];
}
```
#### Method 2: Direct Package Reference
```nix
{
environment.systemPackages = [
inputs.m3ta-nixpkgs.packages.${pkgs.stdenv.hostPlatform.system}.code2prompt
inputs.m3ta-nixpkgs.packages.${pkgs.stdenv.hostPlatform.system}.hyprpaper-random
];
}
```
### Using in Home Manager
#### With Overlay
```nix
{
nixpkgs.overlays = [
inputs.m3ta-nixpkgs.overlays.default
];
home.packages = with pkgs; [
zellij-ps
pomodoro-timer
];
}
```
#### With Home Manager Modules
```nix
{
imports = [
inputs.m3ta-nixpkgs.homeManagerModules.default
# Or specific modules:
# inputs.m3ta-nixpkgs.homeManagerModules.zellij-ps
];
# Module-specific configuration here
}
```
### Using NixOS Modules
```nix
{
imports = [
inputs.m3ta-nixpkgs.nixosModules.default
# Or specific modules:
# inputs.m3ta-nixpkgs.nixosModules.ports
];
# Configure the ports module (if enabled)
m3ta.ports = {
enable = true;
definitions = {
nginx = 80;
ssh = 22;
};
};
}
```
### Building Packages Directly
### Quick Start
```bash
# Build a specific package
# Build a package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt
# Run a package without installing
# Run a package
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
# Install to your profile
nix profile install git+https://code.m3ta.dev/m3tam3re/nixpkgs#msty-studio
# List all available packages
nix flake show git+https://code.m3ta.dev/m3tam3re/nixpkgs
```
## Development Shells
## Documentation
This repository provides pre-configured development environments. All shells are accessible via `nix develop`.
### Available Shells
| Shell | Description | Usage |
| --------- | ---------------------------------------------- | ---------------------- |
| `default` | Nix development tools for working on this repo | `nix develop` |
| `python` | Python with common libraries and tools | `nix develop .#python` |
| `devops` | Docker, Kubernetes, Terraform, cloud CLIs | `nix develop .#devops` |
### Quick Start
```bash
# Enter a development environment
nix develop git+https://code.m3ta.dev/m3tam3re/nixpkgs#python
nix develop git+https://code.m3ta.dev/m3tam3re/nixpkgs#devops
# Run a command in a shell without entering it
nix develop git+https://code.m3ta.dev/m3tam3re/nixpkgs#python --command python --version
```
### Using Shells in Home Manager
Add shells to your home-manager configuration for persistent access:
```nix
{
inputs.m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
# Make tools globally available
home.packages = with inputs.m3ta-nixpkgs.devShells.${pkgs.stdenv.hostPlatform.system};
python.buildInputs ++ devops.buildInputs;
# Or create aliases
programs.zsh.shellAliases = {
dev-python = "nix develop ${inputs.m3ta-nixpkgs}#python";
dev-devops = "nix develop ${inputs.m3ta-nixpkgs}#devops";
};
}
```
### Using Shells in NixOS
Add shells system-wide:
```nix
{
inputs.m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
# Make tools available to all users
environment.systemPackages =
inputs.m3ta-nixpkgs.devShells.${pkgs.stdenv.hostPlatform.system}.python.buildInputs;
# System-wide aliases
environment.shellAliases = {
dev-python = "nix develop ${inputs.m3ta-nixpkgs}#python";
};
}
```
### Project-Specific Usage with direnv
Create `.envrc` in your project directory:
```bash
use flake git+https://code.m3ta.dev/m3tam3re/nixpkgs#python
```
Then run `direnv allow`. The environment activates automatically when you enter the directory!
### Extending Shells for Your Project
Create a `flake.nix` in your project that extends a base shell:
```nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
};
outputs = { nixpkgs, m3ta-nixpkgs, ... }: {
devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
# Inherit all packages from base Python shell
inputsFrom = [ m3ta-nixpkgs.devShells.x86_64-linux.python ];
# Add project-specific packages
buildInputs = [ nixpkgs.legacyPackages.x86_64-linux.postgresql ];
# Project-specific environment variables
DATABASE_URL = "postgresql://localhost/mydb";
};
};
}
```
### Shell Details
See individual shell files for detailed package lists and configuration:
- **Default Shell**: `shells/default.nix` - Nix development tools
- **Python Shell**: `shells/python.nix` - Python development environment
- **DevOps Shell**: `shells/devops.nix` - Infrastructure and cloud tools
## Development
### Setting Up Development Environment
```bash
# Clone the repository
git clone https://code.m3ta.dev/m3tam3re/nixpkgs
cd m3ta-nixpkgs
# Enter development shell
nix develop
# Check flake validity
nix flake check
# Format code
nix fmt
```
### Adding a New Package
1. Create a new directory under `pkgs/`:
```bash
mkdir pkgs/my-package
```
2. Create `pkgs/my-package/default.nix`:
```nix
{
lib,
stdenv,
fetchFromGitHub,
}:
stdenv.mkDerivation rec {
pname = "my-package";
version = "1.0.0";
src = fetchFromGitHub {
owner = "owner";
repo = "repo";
rev = "v${version}";
hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
};
meta = with lib; {
description = "Description of my package";
homepage = "https://github.com/owner/repo";
license = licenses.mit;
maintainers = with maintainers; [ ];
platforms = platforms.linux;
};
}
```
3. Add to `pkgs/default.nix`:
```nix
{
# ... existing packages ...
my-package = pkgs.callPackage ./my-package {};
}
```
### Adding a New NixOS Module
1. Create `modules/nixos/my-module.nix`
2. Add import to `modules/nixos/default.nix`
3. Update `flake.nix` to expose it:
```nix
nixosModules = {
default = ./modules/nixos;
my-module = ./modules/nixos/my-module.nix;
};
```
### Adding a New Home Manager Module
1. Create `modules/home-manager/my-module.nix`
2. Add to `modules/home-manager/default.nix`
3. Update `flake.nix` to expose it:
```nix
homeManagerModules = {
default = import ./modules/home-manager;
my-module = import ./modules/home-manager/my-module.nix;
};
```
## Port Management Module
**NEW!** Centrally manage service ports across your NixOS systems and Home Manager configurations with automatic host-specific overrides.
### Features
- ✅ **Centralized Configuration**: Define all ports in one place
- ✅ **Host-Specific Overrides**: Different ports for different machines (laptop, server, desktop)
- ✅ **Type Safety**: Full NixOS/Home Manager type system integration
- ✅ **Auto-Generated Files**: JSON exports and environment variables
- ✅ **Easy Integration**: Works with any service configuration
- ✅ **Conflict Prevention**: Avoid port conflicts across different hosts
### Quick Start - NixOS Module
```nix
{
imports = [ inputs.m3ta-nixpkgs.nixosModules.default ];
m3ta.ports = {
enable = true;
definitions = {
nginx = 80;
grafana = 3000;
ssh = 22;
prometheus = 9090;
};
hostOverrides = {
laptop = {
nginx = 8080; # Use non-privileged port
ssh = 2222;
};
};
# Automatically uses system hostname
currentHost = config.networking.hostName;
};
# Use ports in your configuration
services.nginx.defaultHTTPListenPort = config.m3ta.ports.get "nginx";
services.openssh.ports = [ (config.m3ta.ports.get "ssh") ];
# Firewall with dynamic ports
networking.firewall.allowedTCPPorts = [
(config.m3ta.ports.get "ssh")
(config.m3ta.ports.get "nginx")
];
}
```
### Quick Start - Home Manager Module
```nix
{
imports = [ inputs.m3ta-nixpkgs.homeManagerModules.default ];
m3ta.ports = {
enable = true;
definitions = {
vite-dev = 5173;
jupyter = 8888;
local-api = 8000;
};
hostOverrides = {
laptop = {
vite-dev = 5174;
jupyter = 9999;
};
};
currentHost = "laptop";
# Auto-generate PORT_* environment variables
generateEnvVars = true;
};
# Use ports in your configuration
programs.bash.shellAliases = {
dev = "PORT=${toString (config.m3ta.ports.get "vite-dev")} npm run dev";
jupyter = "jupyter lab --port=${toString (config.m3ta.ports.get "jupyter")}";
};
home.sessionVariables = {
DEV_SERVER = "http://localhost:${toString (config.m3ta.ports.get "vite-dev")}";
};
}
```
### Available Module Functions
- `config.m3ta.ports.get "service"` - Get port for service on current host
- `config.m3ta.ports.getForHost "host" "service"` - Get port for specific host
- `config.m3ta.ports.all` - All ports for current host (merged defaults + overrides)
- `config.m3ta.ports.allForHost "host"` - All ports for specific host
- `config.m3ta.ports.services` - List all defined service names
### Auto-Generated Files
**NixOS**: `/etc/m3ta/ports.json`
**Home Manager**: `~/.config/m3ta/ports.json`
These files contain all port configuration for easy inspection and external tool integration.
### Using the Library Directly
For advanced use cases, you can use the underlying library functions without the module:
```nix
{
outputs = { nixpkgs, m3ta-nixpkgs, ... }: {
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
modules = [
({ inputs, system, config, ... }: let
m3taLib = inputs.m3ta-nixpkgs.lib.${system};
myPorts = {
ports = { nginx = 80; grafana = 3000; };
hostPorts = { laptop = { nginx = 8080; }; };
};
portHelpers = m3taLib.ports.mkPortHelpers myPorts;
hostname = config.networking.hostName;
in {
services.nginx.port = portHelpers.getPort "nginx" hostname;
})
];
};
};
}
```
### Documentation
See library documentation:
- `lib/ports.nix` - Library source code with inline documentation
Example configurations:
- `examples/nixos-configuration.nix` - NixOS configuration example
- `examples/home-manager-standalone.nix` - Home Manager configuration example
For detailed usage, module documentation, package references, and contribution guidelines, see the [full documentation](./docs).
## Available Packages
@@ -515,6 +59,7 @@ Example configurations:
| `code2prompt` | Convert code to prompts |
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
| `launch-webapp` | Launch web applications |
| `mem0` | AI memory assistant with vector storage |
| `msty-studio` | Msty Studio application |
| `pomodoro-timer` | Pomodoro timer utility |
| `tuxedo-backlight` | Backlight control for Tuxedo laptops |