nixpkgs/QUICKSTART.md

Quick Start Guide - Port Management Module

Get started with centralized port management in 5 minutes!

Installation

Step 1: Add to your flake inputs

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

Step 2: Choose your configuration type

For NixOS Systems

Basic Setup

{
  imports = [ inputs.m3ta-nixpkgs.nixosModules.default ];

  m3ta.ports = {
    enable = true;

    definitions = {
      nginx = 80;
      ssh = 22;
      grafana = 3000;
    };

    hostOverrides = {
      laptop = { nginx = 8080; ssh = 2222; };
      server = {};  # Uses defaults
    };
  };
}

Using Ports

# In any NixOS service configuration:
services.nginx.defaultHTTPListenPort = config.m3ta.ports.get "nginx";
services.openssh.ports = [ (config.m3ta.ports.get "ssh") ];

# Firewall rules:
networking.firewall.allowedTCPPorts = [
  (config.m3ta.ports.get "ssh")
  (config.m3ta.ports.get "nginx")
];

For Home Manager

Basic Setup

{
  imports = [ inputs.m3ta-nixpkgs.homeManagerModules.default ];

  m3ta.ports = {
    enable = true;

    definitions = {
      vite-dev = 5173;
      jupyter = 8888;
      local-api = 8000;
    };

    hostOverrides = {
      laptop = { vite-dev = 5174; };
      desktop = { jupyter = 9999; };
    };

    currentHost = "laptop";  # Set your hostname
    generateEnvVars = true;  # Creates PORT_* environment variables
  };
}

Using Ports

# Shell aliases:
programs.bash.shellAliases = {
  dev = "PORT=${toString (config.m3ta.ports.get "vite-dev")} npm run dev";
};

# Environment variables:
home.sessionVariables = {
  DEV_URL = "http://localhost:${toString (config.m3ta.ports.get "vite-dev")}";
};

# Config files:
home.file.".config/myapp/config.json".text = builtins.toJSON {
  port = config.m3ta.ports.get "vite-dev";
};

Common Patterns

Multi-Host Configuration

# shared-ports.nix
{
  ports = {
    nginx = 80;
    ssh = 22;
    grafana = 3000;
  };

  hostOverrides = {
    laptop = { nginx = 8080; ssh = 2222; };
    server = {};
  };
}

# In your flake.nix
let
  sharedPorts = import ./shared-ports.nix;
in {
  nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
    modules = [
      m3ta-nixpkgs.nixosModules.default
      {
        m3ta.ports = {
          enable = true;
          definitions = sharedPorts.ports;
          hostOverrides = sharedPorts.hostOverrides;
          currentHost = "laptop";
        };
      }
    ];
  };
}

Proxy Configuration

services.nginx.virtualHosts."example.com" = {
  locations."/grafana/" = {
    proxyPass = "http://127.0.0.1:${toString (config.m3ta.ports.get "grafana")}";
  };
  locations."/prometheus/" = {
    proxyPass = "http://127.0.0.1:${toString (config.m3ta.ports.get "prometheus")}";
  };
};

Container Services

virtualisation.oci-containers.containers.grafana = {
  image = "grafana/grafana:latest";
  ports = [
    "${toString (config.m3ta.ports.get "grafana")}:3000"
  ];
};

Available Functions

Function	Description	Example
config.m3ta.ports.get "service"	Get port for current host	config.m3ta.ports.get "nginx"
config.m3ta.ports.getForHost "host" "service"	Get port for specific host	config.m3ta.ports.getForHost "laptop" "nginx"
config.m3ta.ports.all	All ports (merged)	config.m3ta.ports.all
config.m3ta.ports.services	List service names	config.m3ta.ports.services

Debugging

View all configured ports

# NixOS
cat /etc/m3ta/ports.json | jq

# Home Manager
cat ~/.config/m3ta/ports.json | jq

Check what port is being used

# Add to your config temporarily
environment.etc."debug-ports.txt".text = ''
  nginx: ${toString (config.m3ta.ports.get "nginx")}
  ssh: ${toString (config.m3ta.ports.get "ssh")}
  all: ${builtins.toJSON config.m3ta.ports.all}
'';

Next Steps

• See examples/ports/README.md for comprehensive documentation
• Check examples/ports/nixos-example.nix for a full NixOS example
• Check examples/ports/home-manager-example.nix for a full Home Manager example
• Read examples/ports/flake-example.nix for multi-host setup

Common Issues

"Service not defined" error

• Make sure the service is in your definitions block

Wrong port being used

• Check your currentHost matches your actual hostname
• Verify overrides in /etc/m3ta/ports.json or ~/.config/m3ta/ports.json

Type errors

• Ports must be integers: nginx = 80; not nginx = "80";

Need Help?

Open an issue at: https://code.m3ta.dev/m3tam3re/nixpkgs