GEMINI.md

@@ -50,5 +50,5 @@ version: 1.0
 
 > [!IMPORTANT]
 > **Docker Lifecycle Management**
-> Before starting work, the Docker instance of the application must be stopped. After finishing work, a new version from the current branch should be pushed to Docker and the instance restarted. For rapid iterative testing of the web application, you can use `./run-stage.sh --nexus-only` (or `-n`) to rebuild and restart only the web container without resetting database states.
+> Before starting work, only the web (nexus) container needs to be stopped to prevent port/application conflicts (e.g., `./run-stage.sh --stop --nexus-only` or `-s -n`); database containers (PostgreSQL, Neo4j, Qdrant) should continue to run to support local development/debugging. After finishing work, a new version of the web container from the current branch should be rebuilt and restarted via `./run-stage.sh --nexus-only` (or `-n`).
 

run-stage.sh

@@ -5,11 +5,15 @@
 set -e
 
 NEXUS_ONLY=false
+STOP=false
 for arg in "$@"; do
     case $arg in
         --nexus-only|-n)
             NEXUS_ONLY=true
             ;;
+        --stop|-s)
+            STOP=true
+            ;;
     esac
 done
 
@@ -17,6 +21,24 @@ ENV_FILE=".env.stage"
 TEMPLATE_FILE=".env.stage.template"
 COMPOSE_FILE="docker-compose.stage.yml"
 
+if [ "$STOP" = true ]; then
+    echo "🛑 Stopping staging environment..."
+    if [ ! -f "$ENV_FILE" ] && [ -f "$TEMPLATE_FILE" ]; then
+        cp "$TEMPLATE_FILE" "$ENV_FILE"
+    fi
+    if [ "$NEXUS_ONLY" = true ]; then
+        echo "🧹 Stopping and removing only the web (nexus) container..."
+        docker compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" stop web || true
+        docker compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" rm -f web || true
+    else
+        echo "🧹 Stopping all containers..."
+        docker compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" down --remove-orphans || true
+        docker compose down --remove-orphans 2>/dev/null || true
+    fi
+    echo "✅ Staging environment stopped."
+    exit 0
+fi
+
 echo "🏁 Starting staging environment orchestration..."
 if [ "$NEXUS_ONLY" = true ]; then
     echo "ℹ️ Mode: --nexus-only (only the web/nexus application container will be modified)"