quckstart for port management

QUICKSTART_PORT_MANAGEMENT.md

@@ -0,0 +1,230 @@
+# 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}
+'';
+```
+
+## Implementation Details
+
+The port management module is implemented across several files:
+
+- `lib/ports.nix`: Core utilities for port management
+- `modules/nixos/ports.nix`: NixOS module implementation
+- `modules/home-manager/ports.nix`: Home Manager module implementation
+
+For detailed implementation and source code, see these files in the repository.
+
+## 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