+lib +portshelper

examples/ports-example.nix

@@ -0,0 +1,180 @@
+# Example: Using the port management library
+#
+# This example demonstrates how to use the m3ta-nixpkgs port management
+# utilities to centralize port configuration across multiple hosts.
+{
+  inputs,
+  system,
+  ...
+}: let
+  # Import the library
+  m3taLib = inputs.m3ta-nixpkgs.lib.${system};
+
+  # Define all your ports in one central place
+  # This makes it easy to see and manage all port assignments
+  myPortsConfig = {
+    # Default ports for all services
+    ports = {
+      # Web services
+      nginx = 80;
+      nginx-ssl = 443;
+      homepage = 8080;
+      grafana = 3000;
+
+      # Monitoring
+      prometheus = 9090;
+      node-exporter = 9100;
+      loki = 3100;
+
+      # Development
+      dev-server = 8000;
+      dev-api = 8001;
+
+      # Media
+      jellyfin = 8096;
+      transmission = 9091;
+
+      # Other services
+      ssh = 22;
+      gitea = 3001;
+    };
+
+    # Host-specific overrides
+    # Use this when you need different ports on different machines
+    hostPorts = {
+      # On the laptop, run nginx on unprivileged port
+      laptop = {
+        nginx = 8080;
+        nginx-ssl = 8443;
+      };
+
+      # On the server, override specific services
+      server = {
+        homepage = 3002;
+        dev-server = 3003;
+      };
+
+      # On a VM, use different ports to avoid conflicts
+      vm = {
+        nginx = 8888;
+        grafana = 4000;
+        prometheus = 9999;
+      };
+    };
+  };
+
+  # Create the port helper functions
+  ports = m3taLib.ports.mkPortHelpers myPortsConfig;
+
+  # You can also get your hostname dynamically
+  # hostname = config.networking.hostName;
+  hostname = "laptop"; # or "server" or "vm"
+in {
+  # ============================================================================
+  # Example 1: Using in NixOS configuration
+  # ============================================================================
+
+  # Simple usage: get port for current host
+  services.nginx.defaultHTTPListenPort = ports.getPort "nginx" hostname;
+  services.nginx.defaultSSLListenPort = ports.getPort "nginx-ssl" hostname;
+
+  services.grafana.settings.server.http_port = ports.getPort "grafana" hostname;
+  services.prometheus.port = ports.getPort "prometheus" hostname;
+
+  # Without host override (uses default port)
+  services.openssh.ports = [(ports.getPort "ssh" null)];
+
+  # Or use getDefaultPort helper for cleaner syntax
+  services.gitea.settings.server.HTTP_PORT =
+    m3taLib.ports.getDefaultPort myPortsConfig "gitea";
+
+  # ============================================================================
+  # Example 2: Using in Home Manager configuration
+  # ============================================================================
+
+  # Configure development environment with correct ports
+  home.sessionVariables = {
+    DEV_SERVER_PORT = toString (ports.getPort "dev-server" hostname);
+    DEV_API_PORT = toString (ports.getPort "dev-api" hostname);
+  };
+
+  # ============================================================================
+  # Example 3: Advanced usage - get all ports for current host
+  # ============================================================================
+
+  # Get merged view of all ports (defaults + host overrides)
+  environment.etc."service-ports.json".text =
+    builtins.toJSON (ports.getHostPorts hostname);
+
+  # This creates a file at /etc/service-ports.json containing:
+  # {
+  #   "nginx": 8080,        // overridden on laptop
+  #   "nginx-ssl": 8443,    // overridden on laptop
+  #   "homepage": 8080,     // default
+  #   "grafana": 3000,      // default
+  #   ...
+  # }
+
+  # ============================================================================
+  # Example 4: Using in systemd services
+  # ============================================================================
+
+  systemd.services.my-custom-service = {
+    description = "My Custom Service";
+    after = ["network.target"];
+    wantedBy = ["multi-user.target"];
+
+    environment = {
+      PORT = toString (ports.getPort "homepage" hostname);
+    };
+
+    serviceConfig = {
+      ExecStart = "/path/to/service --port ${toString (ports.getPort "homepage" hostname)}";
+    };
+  };
+
+  # ============================================================================
+  # Example 5: Conditional configuration based on host
+  # ============================================================================
+
+  # You can use the same port config across all your machines
+  # and they'll automatically use the right ports
+  services.jellyfin = {
+    enable = true;
+    # Will use 8096 on all hosts (no override defined)
+  };
+
+  # ============================================================================
+  # Example 6: List all configured services
+  # ============================================================================
+
+  # Useful for debugging or documentation
+  environment.etc."configured-services.txt".text =
+    builtins.concatStringsSep "\n" ports.listServices;
+
+  # ============================================================================
+  # Example 7: Using in a flake-based configuration
+  # ============================================================================
+
+  # In your flake.nix:
+  #
+  # {
+  #   inputs = {
+  #     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  #     m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
+  #   };
+  #
+  #   outputs = { self, nixpkgs, m3ta-nixpkgs, ... }: {
+  #     nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
+  #       system = "x86_64-linux";
+  #       specialArgs = {
+  #         inherit inputs system;
+  #       };
+  #       modules = [
+  #         ./configuration.nix
+  #         ./ports-config.nix  # Import this example file
+  #       ];
+  #     };
+  #   };
+  # }
+}