Turn document 2026-05-15 Issues: islandflow-c87, islandflow-2db

# Warn about duplicate VPS compose stacks

Investigated the live VPS, confirmed that a second compose project from the repo-root local-infra stack is still running there, attempted cleanup, and added deploy/docs guardrails so this state is easier to spot and less likely to be recreated accidentally.

## Summary

The live server currently has both `islandflow-vps` and an older `islandflow` compose project. The supported production traffic path uses `islandflow-vps`. I added a deploy-time warning and documentation updates so Docker remains the intended VPS path and the repo-root `docker-compose.yml` is clearly marked as local-only. I also attempted to remove the stale `islandflow` containers on the VPS, but Docker operations against them hung and timed out, so manual cleanup is tracked separately.

## Changes Made

- Updated `scripts/deploy.ts` so Docker runtime prechecks warn when the server also has a compose project named `islandflow`.
- Updated `README.md` to explicitly say the repo-root `docker-compose.yml` is for local infra only and should not be run on the VPS.
- Updated `deployment/docker/README.md` with the same warning and a note about the duplicate-project detector.
- Inspected the live VPS and confirmed that Nginx Proxy Manager routes public traffic to `islandflow-vps` container names on the shared Docker network.
- Attempted `docker compose down` and forced container removal for the stale `islandflow` project, but those operations timed out when run as the normal deploy user.

## Context

The repo has two Docker entry points with different purposes. The root `docker-compose.yml` is a local development infra stack that publishes NATS, ClickHouse, and Redis on host ports. The supported VPS deployment lives under `deployment/docker/` and uses an `islandflow-vps` compose project, internal service-name routing, and Nginx Proxy Manager on the shared Docker network. Running both on the VPS creates duplicate infra and can make host-level debugging confusing.

## Important Implementation Details

- The new warning is advisory only. It does not block Docker deploys, because the current live server still has the duplicate project and production deploys must keep working.
- The detection looks for containers whose compose project label is `islandflow`, which matches the repo-root stack on the VPS.
- The stale containers are still present as of this turn. Removal is blocked by hanging Docker operations and likely needs a maintenance window or host-level intervention.

    [deploy] Warning: found an additional compose project named "islandflow" on the server.
    [deploy] The live VPS should normally use only the deployment/docker stack (compose project "islandflow-vps").
    [deploy] The repo-root docker-compose.yml is for local infra and can create duplicate exposed NATS, ClickHouse, and Redis services on the VPS.

## Validation

- Passed: `./deploy --help`
- Passed: `bun run check:docker-workspace`
- Passed: live VPS inspection confirming duplicate compose containers still exist
- Passed: public app health check after the cleanup attempt, `https://flow.deltaisland.io` still returned HTTP 200

    ssh di 'docker ps --format "{{.Names}} {{.Label \"com.docker.compose.project\"}}" | grep "^islandflow-.* islandflow$" || true'
    curl -I -fksS https://flow.deltaisland.io

## Issues, Limitations, and Mitigations

- The stale VPS containers were not removed in this turn. Mitigation: tracked manual cleanup in `islandflow-2db`.
- Docker commands targeting those old containers hung and timed out. Mitigation: avoided risky broader actions that could impact the live `islandflow-vps` stack.
- The deploy warning is non-blocking. That is intentional so normal Docker deploys continue to work while the duplicate stack is still present.

## Follow-up Work

- Open follow-up: `islandflow-2db`, manually remove the stale `islandflow` local-infra containers from the VPS during a maintenance window.