🐛 fix(ci): prevent container name conflict in staging deployment

- Remove stale containers before deploying (fixes 'name already in use' error)
- Always use --force-recreate flag for consistent deployment behavior
- Add troubleshooting docs for container name conflicts

.github/workflows/cd-staging-tagged.yml

@@ -361,15 +361,18 @@ jobs:
 
             # Service name matches docker-compose service name (with hyphens)
             SERVICE_NAME="$IMAGE_NAME"
+            CONTAINER_NAME="${IMAGE_NAME}-staging"
 
-            if docker compose ps -a | grep -q "$IMAGE_NAME"; then
-              echo "Updating existing service: \$SERVICE_NAME"
-              docker compose up -d --no-deps --force-recreate \$SERVICE_NAME
-            else
-              echo "Service \$SERVICE_NAME not found in compose, starting..."
-              docker compose up -d \$SERVICE_NAME
+            # Remove any stale container with the same name (prevents "name already in use" error)
+            if docker ps -a --format '{{.Names}}' | grep -q "^\$CONTAINER_NAME\$"; then
+              echo "Removing stale container: \$CONTAINER_NAME"
+              docker rm -f \$CONTAINER_NAME 2>/dev/null || true
             fi
 
+            # Always use --force-recreate to ensure the new image is used
+            echo "Deploying service: \$SERVICE_NAME"
+            docker compose up -d --no-deps --force-recreate \$SERVICE_NAME
+
             # Wait for startup
             sleep 10
             docker compose ps \$SERVICE_NAME

cicd/DEPLOYMENT.md

@@ -543,6 +543,20 @@ docker logs chat-backend-staging --tail 200
 # - Port conflicts
 ```
 
+### Container name conflict error
+
+If you see: `Error: The container name "/xxx-staging" is already in use`
+
+```bash
+# SSH to server and remove the stale container
+ssh deploy@46.224.108.214
+docker rm -f todo-web-staging  # Replace with actual container name
+
+# Then re-run the deployment
+```
+
+This can happen if a container was created outside of docker-compose or if a previous deployment failed mid-way.
+
 ---
 
 ## Managing Tags