nixpkgs/examples/ports-example.nix

# 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
  #       ];
  #     };
  #   };
  # }
}