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

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

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

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

```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; };
      desktop = { jupyter = 9999; };
    };

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

### Using Ports

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

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

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

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

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

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

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

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

### Check what port is being used

```nix
# 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](examples/ports/README.md) for comprehensive documentation
- Check [examples/ports/nixos-example.nix](examples/ports/nixos-example.nix) for a full NixOS example
- Check [examples/ports/home-manager-example.nix](examples/ports/home-manager-example.nix) for a full Home Manager example
- Read [examples/ports/flake-example.nix](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