nixpkgs/README.md

# m3ta-nixpkgs

My personal Nix repository containing 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
- ⚙️ **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

```
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
```

## Usage

### Adding to Your Flake

Add this repository to your flake inputs:

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
  };
}
```

### 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.${system}.code2prompt
    inputs.m3ta-nixpkgs.packages.${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

```bash
# Build a specific package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt

# Run a package without installing
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

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.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.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

## Available Packages

| Package            | Description                           |
| ------------------ | ------------------------------------- |
| `code2prompt`      | Convert code to prompts               |
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
| `launch-webapp`    | Launch web applications               |
| `msty-studio`      | Msty Studio application               |
| `pomodoro-timer`   | Pomodoro timer utility                |
| `tuxedo-backlight` | Backlight control for Tuxedo laptops  |
| `zellij-ps`        | Process viewer for Zellij             |

## License

Individual packages may have their own licenses. Check each package's `meta.license` attribute.

## Maintainer

[@m3tam3re](https://m3ta.dev)