SIENTIAPDE-1255: Add port forwarding setup script and documentation to README.md

README.md

@@ -24,6 +24,7 @@ A comprehensive AI model management platform for the complete machine learning l
   - [Environment Setup](#environment-setup)
   - [Temporal Namespace Setup](#temporal-namespace-setup)
   - [Local Development Setup](#local-development-setup)
+    - [Port Forward Setup Script](#port-forward-setup-script)
 - [How to Run](#how-to-run)
   - [Running the Model Manager Application](#running-the-model-manager-application)
   - [Running Tests and Coverage](#running-tests-and-coverage)
@@ -708,17 +709,82 @@ kubectl exec -n temporal <temporal-admin-tools-pod-name> -- \
 
 5. **Configure external dependencies**
    
-   You'll need to set up port forwarding or connections to external services. For example:
+   The Model Manager requires connections to several external services. For local development, you can use the provided port-forward script to establish connections to services running in your Kubernetes cluster.
 
-   ```bash
+#### Port Forward Setup Script
-   # Port forwarding from Kubernetes cluster
-   kubectl port-forward svc/postgresql 5432:5432
-   kubectl port-forward svc/mlflow 5000:5000
-   kubectl port-forward svc/mongodb 27017:27017
 
-   # Or connect to external services
+The `setup_port_forwards.sh` script automates the creation of port forwards to all required services:
-   # Ensure services are accessible on localhost with appropriate ports
+
-   ```
+**Features:**
+- 🔄 **Automatic Cleanup**: Kills existing port-forward jobs for the same services
+- ✅ **Port Validation**: Checks if ports are available before creating forwards
+- 🛡️ **Safe Execution**: Stops if any port is already in use by another process
+- 📊 **Clear Output**: Color-coded status messages and service information
+
+**Usage:**
+
+```bash
+# Make script executable (first time only)
+chmod +x setup_port_forwards.sh
+
+# Run the script
+./setup_port_forwards.sh
+```
+
+**Services and Ports:**
+
+| Local Port | Service | Description | Namespace |
+|------------|---------|-------------|-----------|
+| `5432` | `paradedb-rw` | PostgreSQL Database | `paradedb` |
+| `45249` | `sientia-tracker-mlflow-tracking` | MLflow Tracking Server | `sientia-tracker` |
+| `37463` | `temporal-frontend` | Temporal gRPC API | `temporal` |
+| `8080` | `temporal-web` | Temporal Web UI | `temporal` |
+| `42297` | `my-release-mongodb` | MongoDB Database | `mongodb` |
+| `36577` | `minio` | MinIO Object Storage | `minio` |
+
+**Managing Port Forwards:**
+
+```bash
+# View active port forwards
+jobs -l
+
+# Stop all port forwards
+jobs -p | xargs kill
+
+# Stop and restart (using the script)
+./setup_port_forwards.sh
+```
+
+**Troubleshooting:**
+
+If you encounter port conflicts:
+1. The script will show which ports are in use
+2. Stop the conflicting process or use the script to kill existing port-forwards
+3. Run the script again
+
+**Manual Port Forwarding:**
+
+If you prefer manual control or need different ports:
+
+```bash
+# PostgreSQL
+kubectl -n paradedb port-forward svc/paradedb-rw 5432:5432 &
+
+# MLflow
+kubectl -n sientia-tracker port-forward svc/sientia-tracker-mlflow-tracking 45249:80 &
+
+# Temporal
+kubectl -n temporal port-forward svc/temporal-frontend 37463:7233 &
+
+# Temporal UI
+kubectl -n temporal port-forward svc/temporal-web 8080:8080 &
+
+# MongoDB
+kubectl -n mongodb port-forward svc/my-release-mongodb 42297:27017 &
+
+# MinIO
+kubectl -n minio port-forward svc/minio 36577:9000 &
+```
 
 ## How to Run
 

setup_port_forwards.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+
+# Exit on any error
+set -e
+
+# Color codes for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}=== Port Forward Setup Script ===${NC}\n"
+
+# Define port forwards: LOCAL_PORT:NAMESPACE:SERVICE:REMOTE_PORT:DESCRIPTION
+PORT_FORWARDS=(
+    "5432:paradedb:paradedb-rw:5432:PostgreSQL"
+    "45249:sientia-tracker:sientia-tracker-mlflow-tracking:80:MLflow"
+    "37463:temporal:temporal-frontend:7233:Temporal"
+    "8080:temporal:temporal-web:8080:Temporal UI"
+    "42297:mongodb:my-release-mongodb:27017:MongoDB"
+    "36577:minio:minio:9000:MinIO"
+)
+
+# Step 1: Kill existing port-forward jobs for these services
+echo -e "${YELLOW}Step 1: Checking for existing port-forward jobs...${NC}"
+
+for pf in "${PORT_FORWARDS[@]}"; do
+    IFS=':' read -r local_port namespace service remote_port description <<< "$pf"
+    
+    # Check if there's a job with this service name
+    existing_jobs=$(jobs -l | grep "kubectl.*port-forward.*svc/$service" || true)
+    
+    if [ -n "$existing_jobs" ]; then
+        echo -e "${YELLOW}  Found existing port-forward for $description ($service)${NC}"
+        # Extract PIDs and kill them
+        pids=$(echo "$existing_jobs" | awk '{print $2}')
+        for pid in $pids; do
+            echo -e "${YELLOW}  Killing job with PID $pid${NC}"
+            kill "$pid" 2>/dev/null || true
+        done
+    fi
+done
+
+# Wait a moment for ports to be released
+sleep 1
+
+echo -e "${GREEN}  Cleanup complete${NC}\n"
+
+# Step 2: Check if any of the ports are already in use
+echo -e "${YELLOW}Step 2: Checking if ports are available...${NC}"
+
+ports_in_use=()
+
+for pf in "${PORT_FORWARDS[@]}"; do
+    IFS=':' read -r local_port namespace service remote_port description <<< "$pf"
+    
+    # Check if port is in use using lsof or netstat
+    if command -v lsof &> /dev/null; then
+        if lsof -Pi :$local_port -sTCP:LISTEN -t >/dev/null 2>&1; then
+            ports_in_use+=("$local_port:$description")
+        fi
+    elif command -v netstat &> /dev/null; then
+        if netstat -tuln | grep -q ":$local_port "; then
+            ports_in_use+=("$local_port:$description")
+        fi
+    elif command -v ss &> /dev/null; then
+        if ss -tuln | grep -q ":$local_port "; then
+            ports_in_use+=("$local_port:$description")
+        fi
+    fi
+done
+
+# If any ports are in use, report and exit
+if [ ${#ports_in_use[@]} -gt 0 ]; then
+    echo -e "${RED}ERROR: The following ports are already in use:${NC}"
+    for port_info in "${ports_in_use[@]}"; do
+        IFS=':' read -r port desc <<< "$port_info"
+        echo -e "${RED}  - Port $port (for $desc)${NC}"
+    done
+    echo -e "\n${RED}Please free these ports before running this script.${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}  All ports are available${NC}\n"
+
+# Step 3: Create all port forwards
+echo -e "${YELLOW}Step 3: Creating port forwards...${NC}"
+
+for pf in "${PORT_FORWARDS[@]}"; do
+    IFS=':' read -r local_port namespace service remote_port description <<< "$pf"
+    
+    echo -e "${GREEN}  Starting port-forward: $description${NC}"
+    echo -e "    Local port: $local_port -> $namespace/$service:$remote_port"
+    
+    kubectl -n "$namespace" port-forward "svc/$service" "$local_port:$remote_port" &
+    
+    # Give it a moment to start
+    sleep 0.5
+done
+
+echo -e "\n${GREEN}=== All port forwards created successfully ===${NC}"
+echo -e "\n${YELLOW}Active port forwards:${NC}"
+for pf in "${PORT_FORWARDS[@]}"; do
+    IFS=':' read -r local_port namespace service remote_port description <<< "$pf"
+    echo -e "  - ${GREEN}localhost:$local_port${NC} -> $description ($namespace/$service)"
+done
+
+echo -e "\n${YELLOW}To stop all port forwards, run:${NC}"
+echo -e "  jobs -p | xargs kill"
+echo -e "\n${YELLOW}To view active port forwards:${NC}"
+echo -e "  jobs -l"