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:

{
  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

{
  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

{
  environment.systemPackages = [
    inputs.m3ta-nixpkgs.packages.${system}.code2prompt
    inputs.m3ta-nixpkgs.packages.${system}.hyprpaper-random
  ];
}

Using in Home Manager

With Overlay

{
  nixpkgs.overlays = [
    inputs.m3ta-nixpkgs.overlays.default
  ];

  home.packages = with pkgs; [
    zellij-ps
    pomodoro-timer
  ];
}

With Home Manager Modules

{
  imports = [
    inputs.m3ta-nixpkgs.homeManagerModules.default
    # Or specific modules:
    # inputs.m3ta-nixpkgs.homeManagerModules.zellij-ps
  ];

  # Module-specific configuration here
}

Using NixOS Modules

{
  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

# 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

# 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:

{
  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:

{
  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:

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:

{
  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

# 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/:

mkdir pkgs/my-package

2. Create pkgs/my-package/default.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:

{
  # ... 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:

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:

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

{
  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

{
  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:

{
  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