nixpkgs/docs/modules/nixos/ports.md

# ports NixOS Module

Port management module for NixOS.

## Overview

This module provides centralized port management across multiple hosts. Define default ports and host-specific overrides to prevent conflicts.

See [Port Management Guide](../../guides/port-management.md) for detailed usage.

## Quick Start

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;

    # Define default ports
    definitions = {
      nginx = 80;
      grafana = 3000;
      prometheus = 9090;
    };

    # Host-specific overrides
    hostOverrides = {
      laptop = {
        nginx = 8080;
        grafana = 3001;
      };
    };

    # Current host
    currentHost = config.networking.hostName;
  };
}
```

## Module Options

### `m3ta.ports.enable`

Enable port management.

- Type: `boolean`
- Default: `false`

### `m3ta.ports.definitions`

Default port definitions.

- Type: `attrsOf int`
- Default: `{}`

Example:

```nix
definitions = {
  nginx = 80;
  grafana = 3000;
  prometheus = 9090;
};
```

### `m3ta.ports.hostOverrides`

Host-specific port overrides.

- Type: `attrsOf (attrsOf int)`
- Default: `{}`

Example:

```nix
hostOverrides = {
  laptop = {
    nginx = 8080;
    grafana = 3001;
  };
  server = {
    nginx = 80;
    prometheus = 9091;
  };
};
```

### `m3ta.ports.currentHost`

Current hostname. Determines which overrides to apply.

- Type: `string`
- Example: `config.networking.hostName`

## Functions

### `config.m3ta.ports.get "service"`

Get port for a service with host-specific override.

```nix
services.nginx = {
  port = config.m3ta.ports.get "nginx";
};
```

If current host is `laptop` and `hostOverrides.laptop.nginx = 8080`, returns `8080`.
If no override, returns default `80`.

### `config.m3ta.ports.getHostPorts "hostname"`

Get all ports for a specific host.

```nix
# Get all ports for laptop
laptopPorts = config.m3ta.ports.getHostPorts "laptop";
# Returns: { nginx = 8080; grafana = 3000; ... }
```

### `config.m3ta.ports.listServices`

List all defined service names.

```nix
allServices = config.m3ta.ports.listServices;
# Returns: ["nginx" "grafana" "prometheus"]
```

## Usage Examples

### Basic Usage

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
    };
    currentHost = "server";
  };

  services.nginx = {
    enable = true;
    httpConfig = ''
      server {
        listen ${toString (config.m3ta.ports.get "nginx")};
      }
    '';
  };
}
```

### Multi-Host Setup

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
      prometheus = 9090;
    };
    hostOverrides = {
      laptop = {
        nginx = 8080;
        grafana = 3001;
      };
      server = {
        nginx = 80;
        grafana = 3000;
      };
    };
    currentHost = config.networking.hostName;
  };

  services.nginx = {
    enable = true;
    httpConfig = ''
      server {
        listen ${toString (config.m3ta.ports.get "nginx")};
      }
    '';
  };
}
```

### With Multiple Services

```nix
{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      # Monitoring
      grafana = 3000;
      prometheus = 9090;
      loki = 3100;
      promtail = 9080;

      # Web
      nginx = 80;

      # Databases
      postgres = 5432;
      redis = 6379;
      qdrant = 6333;
    };
    currentHost = config.networking.hostName;
  };

  # Use ports
  services.grafana = {
    enable = true;
    settings.server.http_port = config.m3ta.ports.get "grafana";
  };

  services.postgresql = {
    enable = true;
    port = config.m3ta.ports.get "postgres";
  };
}
```

## Related

- [Port Management Guide](../../guides/port-management.md) - Detailed guide
- [Home Manager Ports Module](../home-manager/ports.md) - User-level port management