modules for ports

2025-10-05 09:44:40 +02:00
parent 56295f694d
commit 62a85af9bc
5 changed files with 316 additions and 291 deletions
--- a/README.md
+++ b/README.md
@@ -32,15 +32,21 @@ m3ta-nixpkgs/
 │       └── n8n.nix
 ├── modules/
 │   ├── nixos/                  # NixOS modules
-│   │   └── default.nix
+│   │   ├── 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
-│   └── ports-example.nix
+│   └── ports/                  # Port management examples
+│       ├── README.md
+│       ├── nixos-example.nix
+│       ├── home-manager-example.nix
+│       └── flake-example.nix
 └── templates/                   # Templates for new packages/modules
 ```

@@ -126,9 +132,18 @@ Add this repository to your flake inputs:
 {
  imports = [
    inputs.m3ta-nixpkgs.nixosModules.default
+    # Or specific modules:
+    # inputs.m3ta-nixpkgs.nixosModules.ports
  ];

-  # Your custom module options will be available here
+  # Configure the ports module (if enabled)
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      nginx = 80;
+      ssh = 22;
+    };
+  };
 }
 ```

@@ -239,56 +254,134 @@ homeManagerModules = {
 };
 ```

-### Using Library Functions
+## Port Management Module

-The repository includes helper functions to simplify common configuration tasks.
+**NEW!** Centrally manage service ports across your NixOS systems and Home Manager configurations with automatic host-specific overrides.

-#### Port Management
+### Features

-Centrally manage service ports across multiple hosts with automatic host-specific overrides:
+- ✅ **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
-# In your flake.nix or configuration
 {
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
-    m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
+  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;
  };

-  outputs = { self, nixpkgs, m3ta-nixpkgs, ... }: {
+  # 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 {
-      system = "x86_64-linux";
-      specialArgs = { inherit inputs; system = "x86_64-linux"; };
      modules = [
        ({ inputs, system, config, ... }: let
-          # Import the library
          m3taLib = inputs.m3ta-nixpkgs.lib.${system};

-          # Define all ports in one place
          myPorts = {
-            ports = {
-              nginx = 80;
-              grafana = 3000;
-              prometheus = 9090;
-            };
-            hostPorts = {
-              laptop = {
-                nginx = 8080;  # Non-privileged port on laptop
-              };
-            };
+            ports = { nginx = 80; grafana = 3000; };
+            hostPorts = { laptop = { nginx = 8080; }; };
          };

-          # Create helper functions
-          ports = m3taLib.ports.mkPortHelpers myPorts;
+          portHelpers = m3taLib.ports.mkPortHelpers myPorts;
          hostname = config.networking.hostName;
        in {
-          # Use in your configuration
-          services.nginx.defaultHTTPListenPort = ports.getPort "nginx" hostname;
-          services.grafana.settings.server.http_port = ports.getPort "grafana" hostname;
-
-          # Get all ports for current host
-          environment.etc."service-ports.json".text =
-            builtins.toJSON (ports.getHostPorts hostname);
+          services.nginx.port = portHelpers.getPort "nginx" hostname;
        })
      ];
    };
@@ -296,22 +389,15 @@ Centrally manage service ports across multiple hosts with automatic host-specifi
 }
 ```

-**Benefits:**
+### Documentation

- Single source of truth for all port assignments
- Automatic host-specific overrides (laptop, server, VM, etc.)
- Works across both NixOS and Home Manager configurations
- Easy to see and manage all ports in one place
+See comprehensive examples and documentation:

-**Available Functions:**
-
- `mkPortHelpers`: Create port helper functions from a configuration
- `getPort`: Get port for a service with optional host override
- `getHostPorts`: Get all ports for a specific host (merged defaults + overrides)
- `getDefaultPort`: Get default port without host override
- `listServices`: List all defined service names
-
-See `examples/ports-example.nix` for comprehensive usage examples.
+- `examples/ports/README.md` - Complete guide with all features
+- `examples/ports/nixos-example.nix` - Full NixOS configuration example
+- `examples/ports/home-manager-example.nix` - Full Home Manager configuration example
+- `examples/ports/flake-example.nix` - Complete multi-host flake setup
+- `lib/ports.nix` - Library source code with inline documentation

 ## Available Packages