chore: update dev scripts and documentation

scripts/start_services_dev.ps1

@@ -1,13 +1,12 @@
 #!/usr/bin/env pwsh
 # Start Dograh services in development mode (Windows)
-# Usage: .\scripts\start_services_dev.ps1 [-ArqWorkers 2] [-NoMigrations] [-IncludeTelephonyWorkers]
+# Usage: .\scripts\start_services_dev.ps1 [-NoMigrations] [-IncludeTelephonyWorkers]
 #
 # Note: Telephony workers (ari_manager, campaign_orchestrator) are disabled by
 # default on Windows because they use Unix signal handlers not supported by the
 # Windows asyncio event loop.
 
 Param(
-    [int]$ArqWorkers = 1,
     [switch]$NoMigrations,
     [switch]$IncludeTelephonyWorkers
 )
@@ -61,10 +60,7 @@ if ($IncludeTelephonyWorkers) {
 }
 
 $serviceSpecs += @{ Name = 'uvicorn'; Cmd = "uvicorn api.app:app --host 0.0.0.0 --port $($env:UVICORN_BASE_PORT) --reload --reload-dir api" }
-
-for ($i = 1; $i -le $ArqWorkers; $i++) {
-    $serviceSpecs += @{ Name = "arq$i"; Cmd = "python -m arq api.tasks.arq.WorkerSettings --custom-log-dict api.tasks.arq.LOG_CONFIG" }
-}
+$serviceSpecs += @{ Name = 'arq';     Cmd = "python -m arq api.tasks.arq.WorkerSettings --custom-log-dict api.tasks.arq.LOG_CONFIG" }
 
 ###############################################################################
 ### 3) Activate virtual environment

scripts/start_services_dev.sh

@@ -17,7 +17,6 @@ LOG_DIR="$BASE_LOG_DIR/$TIMESTAMP"      # Timestamped log directory
 LATEST_LINK="$BASE_LOG_DIR/latest"      # Symlink to latest logs
 VENV_PATH="$BASE_DIR/venv"
 
-ARQ_WORKERS=${ARQ_WORKERS:-1}
 LOG_TO_FILE=${LOG_TO_FILE:-true}
 
 cd "$BASE_DIR"
@@ -42,20 +41,16 @@ SERVICE_NAMES=(
   "ari_manager"
   "campaign_orchestrator"
   "uvicorn"
+  "arq"
 )
 
 SERVICE_COMMANDS=(
   "python -m api.services.telephony.ari_manager"
   "python -m api.services.campaign.campaign_orchestrator"
   "uvicorn api.app:app --host 0.0.0.0 --port $UVICORN_BASE_PORT --reload --reload-dir api"
+  "python -m arq api.tasks.arq.WorkerSettings --custom-log-dict api.tasks.arq.LOG_CONFIG"
 )
 
-# Add ARQ workers dynamically
-for ((i=1; i<=ARQ_WORKERS; i++)); do
-  SERVICE_NAMES+=("arq$i")
-  SERVICE_COMMANDS+=("python -m arq api.tasks.arq.WorkerSettings --custom-log-dict api.tasks.arq.LOG_CONFIG")
-done
-
 ###############################################################################
 ### 3) Activate virtual environment
 ###############################################################################
@@ -217,6 +212,3 @@ echo "Logs: tail -f $LOG_DIR/*.log"
 echo "Rotated logs: ls $LOG_DIR/*.log.*"
 echo "To stop: ./scripts/stop_services.sh"
 echo "──────────────────────────────────────────────────"
-
-# Keep the script alive (required for Docker - PID 1 must not exit)
-wait

scripts/start_services_docker.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -e
+
+###############################################################################
+### CONFIGURATION
+###############################################################################
+
+BASE_DIR="$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)"
+ENV_FILE="$BASE_DIR/api/.env"
+
+ARQ_WORKERS=${ARQ_WORKERS:-1}
+FASTAPI_WORKERS=${FASTAPI_WORKERS:-1}
+UVICORN_BASE_PORT=${UVICORN_BASE_PORT:-8000}
+
+cd "$BASE_DIR"
+echo "Starting Dograh Services (DOCKER) at $(date) in BASE_DIR: ${BASE_DIR}"
+
+###############################################################################
+### 1) Load env file if mounted (env normally comes from docker-compose)
+###############################################################################
+
+if [[ -f "$ENV_FILE" ]]; then
+  set -a && . "$ENV_FILE" && set +a
+fi
+
+###############################################################################
+### 2) Run migrations
+###############################################################################
+
+alembic -c "$BASE_DIR/api/alembic.ini" upgrade head
+
+###############################################################################
+### 3) Signal handling — forward TERM/INT to children for clean docker stop
+###############################################################################
+
+pids=()
+
+shutdown() {
+  echo "Received shutdown signal, stopping services..."
+  for pid in "${pids[@]}"; do
+    kill -TERM "$pid" 2>/dev/null || true
+  done
+  wait
+  exit 0
+}
+
+trap shutdown TERM INT
+
+start() {
+  local name=$1
+  shift
+  echo "→ Starting $name"
+  "$@" &
+  pids+=($!)
+  echo "  $name PID $!"
+}
+
+###############################################################################
+### 4) Start services (logs go to stdout for `docker logs`)
+###############################################################################
+
+start ari_manager           python -m api.services.telephony.ari_manager
+start campaign_orchestrator python -m api.services.campaign.campaign_orchestrator
+start uvicorn               uvicorn api.app:app --host 0.0.0.0 --port "$UVICORN_BASE_PORT" --workers "$FASTAPI_WORKERS"
+
+for ((i=1; i<=ARQ_WORKERS; i++)); do
+  start "arq$i" python -m arq api.tasks.arq.WorkerSettings --custom-log-dict api.tasks.arq.LOG_CONFIG
+done
+
+###############################################################################
+### 5) Wait — if any service exits, tear the container down so docker restarts
+###############################################################################
+
+wait -n
+echo "A service exited; tearing down container."
+shutdown