docs/ARCHITECTURE.md

@@ -832,14 +832,14 @@ Environments:
 
 ### Container labels
 
-Every Docker resource Galaxy creates carries an opinionated label so
+Every Galaxy-managed Docker **container** carries an opinionated
-that host-side tooling (Makefiles, CI workflows, `preclean.sh`) can
+label so that host-side tooling (Makefiles, CI workflows,
-scope its operations to Galaxy-owned objects and never touch unrelated
+`preclean.sh`) can scope its operations to Galaxy-owned containers
-workloads on the shared daemon.
+and never touch unrelated workloads on the shared daemon.
 
 | Label | Values | Set by | Used by |
 |-------|--------|--------|---------|
-| `galaxy.stack` | `local-dev`, `dev-deploy`, `integration` | `tools/{local-dev,dev-deploy}/docker-compose.yml` for compose-managed resources; backend reads `BACKEND_STACK_LABEL` and stamps engines it spawns. | `tools/{local-dev,dev-deploy}/Makefile`, `.gitea/workflows/dev-deploy.yaml`. |
+| `galaxy.stack` | `local-dev`, `dev-deploy`, `integration` | `tools/{local-dev,dev-deploy}/docker-compose.yml` for compose-managed services; backend reads `BACKEND_STACK_LABEL` and stamps engines it spawns. | `tools/{local-dev,dev-deploy}/Makefile`, `.gitea/workflows/dev-deploy.yaml`. |
 | `galaxy.backend` | `1` | `backend/internal/dockerclient` adapter on every engine container. | `integration/scripts/preclean.sh`. |
 | `galaxy.game_id` | `<uuid>` | Backend on engine create. | Reconciler reattach loop. |
 | `galaxy.engine_version` | `<semver>` | Backend on engine create. | Reconciler version checks. |
@@ -853,6 +853,15 @@ scoped by their compose project name (`galaxy-dev`, `galaxy-local-dev`),
 which Compose enforces on `docker compose up/down`; the labels make the
 contract explicit and survive hand-rolled cleanup commands as well.
 
+**Scope deliberately limited to containers.** Labels are NOT stamped
+on named volumes or user-defined networks. Adding labels there would
+change the compose config-hash for the volume/network on every label
+revision and force `docker compose up` to recreate them — which for a
+postgres data volume means destroying the database, and for a shared
+network can deadlock if any container is still attached. Containers
+alone are sufficient for the cleanup contract; stateful resources stay
+untouched by compose between deploys.
+
 ## 19. Deployment Topology (informational)
 
 - MVP runs three executables: one `gateway` instance, one `backend`

tools/dev-deploy/docker-compose.yml

@@ -238,22 +238,23 @@ networks:
     name: galaxy-dev-internal
     driver: bridge
     internal: false
-    labels:
-      galaxy.stack: dev-deploy
   edge:
     name: ${GALAXY_EDGE_NETWORK:-edge}
     external: true
 
+# Note: `galaxy.stack=dev-deploy` is intentionally stamped only on
+# services (containers). Stamping it on networks or named volumes
+# changes the compose config-hash for those resources, and on a
+# subsequent `compose up` compose tries to recreate them — for the
+# `galaxy-dev-postgres-data` volume that means destroying the
+# database, and for `galaxy-dev-internal` it can deadlock if any
+# container is still attached. Per-container labels are sufficient
+# for the CI/cleanup contract; we filter containers, not volumes or
+# networks.
 volumes:
   galaxy-dev-postgres-data:
     name: galaxy-dev-postgres-data
-    labels:
-      galaxy.stack: dev-deploy
   galaxy-dev-caddy-data:
     name: galaxy-dev-caddy-data
-    labels:
-      galaxy.stack: dev-deploy
   galaxy-dev-ui-dist:
     name: galaxy-dev-ui-dist
-    labels:
-      galaxy.stack: dev-deploy

tools/local-dev/docker-compose.yml

@@ -218,11 +218,10 @@ services:
 networks:
   galaxy-net:
     name: galaxy-local-dev-net
-    labels:
-      galaxy.stack: local-dev
 
+# See note in tools/dev-deploy/docker-compose.yml — labels live only
+# on services (containers), not on volumes or networks, to keep the
+# compose config-hash for stateful resources stable across deploys.
 volumes:
   postgres-data:
     name: galaxy-local-dev-postgres-data
-    labels:
-      galaxy.stack: local-dev