fix(shared): docker test image cleanup

CONTRIBUTING.md

@@ -47,6 +47,87 @@ We welcome contributions of all kinds:
    - Run through local setup and run the app (see [project docs](./docs/agenstra/README.md) for entry points)
    - Understand the repository layout and how to run tests and builds
 
+### Local Containers and Disk Usage
+
+Run an application's local stack with `npx nx run <project>:start-containers`.
+The following 13 applications expose this target and build 14 local test images.
+Image names below use `ghcr.io/forepath/` and `:latest`, except for the manager's
+worker, which uses `registry.forenet.internal/forepath/agenstra-manager-worker:test`.
+
+| Project                                                                                  | Test image name(s)                                | Build prerequisite | Image usage                                                |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| [agenstra-backend-agent-controller](apps/agenstra/backend-agent-controller/project.json) | `agenstra-controller-api`                         | `prune`            | API, scheduler, and worker Compose services                |
+| [agenstra-backend-agent-manager](apps/agenstra/backend-agent-manager/project.json)       | `agenstra-manager-api`, `agenstra-manager-worker` | `prune`            | API Compose service; worker containers created dynamically |
+| [agenstra-frontend-agent-console](apps/agenstra/frontend-agent-console/project.json)     | `agenstra-console-server`                         | `server`           | Console server                                             |
+| [agenstra-frontend-billing-console](apps/agenstra/frontend-billing-console/project.json) | `agenstra-billing-console-server`                 | `server`           | Billing console server                                     |
+| [agenstra-frontend-docs](apps/agenstra/frontend-docs/project.json)                       | `agenstra-docs-server`                            | `postbuild`        | Documentation server                                       |
+| [agenstra-frontend-landingpage](apps/agenstra/frontend-landingpage/project.json)         | `agenstra-landingpage-server`                     | `postbuild`        | Landing page server                                        |
+| [decabill-backend-billing-manager](apps/decabill/backend-billing-manager/project.json)   | `decabill-billing-api`                            | `prune`            | API, scheduler, and worker Compose services                |
+| [decabill-frontend-billing-console](apps/decabill/frontend-billing-console/project.json) | `decabill-billing-console-server`                 | `server`           | Billing console server                                     |
+| [decabill-frontend-docs](apps/decabill/frontend-docs/project.json)                       | `decabill-docs-server`                            | `postbuild`        | Documentation server                                       |
+| [decabill-frontend-landingpage](apps/decabill/frontend-landingpage/project.json)         | `decabill-landingpage-server`                     | `postbuild`        | Landing page server                                        |
+| [forepath-backend-communication](apps/forepath/backend-communication/project.json)       | `forepath-communication-api`                      | `prune`            | API Compose service                                        |
+| [forepath-frontend-billing-console](apps/forepath/frontend-billing-console/project.json) | `forepath-billing-console-server`                 | `server`           | Billing console server                                     |
+| [forepath-frontend-landingpage](apps/forepath/frontend-landingpage/project.json)         | `forepath-landingpage-server`                     | `postbuild`        | Landing page server                                        |
+
+All image targets use `@nx-tools/nx-container:build`, default to the `test`
+configuration, disable Nx caching, pass the `VERSION` build argument, and load
+the result into the local Docker image store with `load: true`. Docker layer
+caching still applies. The build paths are:
+
+- Backends: `prune` prepares the compiled app, pruned dependencies, and workspace
+  modules under `dist/apps/<domain>/<app>`. It is an Nx packaging target, not
+  Docker cleanup. API Dockerfiles use Debian, install the runtime and production
+  dependencies, copy the app, and launch `main.js` through an entrypoint. Agenstra
+  and Decabill also prepare migrations and provider-plugin installation assets.
+- Agent and billing consoles: `server` follows `prebuild-server` and prepares
+  `dist/apps/<domain>/<app>/server`. Node Alpine images install production
+  dependencies, copy the server output, and launch `server.cjs`. All three billing
+  consoles share Decabill's Dockerfile and Compose definition; environment
+  variables select the appropriate image and container name.
+- Landing pages and documentation: `postbuild` follows `build` and
+  `build-delegating-server`, assembling `dist/apps/<domain>/<app>/server`.
+  Node Alpine images copy that output and launch `server.mjs`. Both documentation
+  apps share the documentation Dockerfile and Compose definition, with
+  environment variables selecting their image and container name.
+- Manager worker: a separate Debian image installs the desktop, development
+  tools, and OpenCode, and copies `worker-desktop` assets from the manager's build
+  output. Compose does not start this image. The manager's Docker service creates
+  agent containers from `AGENT_DEFAULT_IMAGE`, whose Compose default is
+  `ghcr.io/forepath/agenstra-manager-worker:latest`. To use the locally built test
+  worker, explicitly set it to the internal-registry `:test` reference above.
+
+Compose uses `pull_policy: never` for the application services and runs
+`up -d --force-recreate --remove-orphans`. Infrastructure images such as
+PostgreSQL, Redis, OpenSearch, and MailHog are separate pulled images.
+
+Repeated starts do not necessarily create new image IDs: an unchanged Docker
+build can reuse its cached image. However, a changed build moves the fixed tag to
+a new image, leaving the previous image dangling once the old containers are
+recreated. Compose's `--remove-orphans` removes containers, not images. Without
+cleanup, these obsolete images can accumulate; this was reproduced with Docker.
+
+Each test image now carries `io.forepath.one.test-project=<project>`. After a
+successful Compose start, the target runs:
+
+```bash
+docker image prune --force --filter label=io.forepath.one.test-project=<project>
+```
+
+Without `--all`, this removes only that project's dangling, unused test images.
+Tagged images, images referenced by running or stopped containers, other
+projects' images, release images, and volumes are preserved. Failed starts and
+standalone image builds do not run cleanup; a later successful start can reclaim
+their obsolete labeled images. Release builds remain unlabeled and unchanged.
+
+Images built before labeling cannot be safely attributed to a project by this
+cleanup. Inspect `docker system df -v` and `docker image ls --filter dangling=true`
+before manually removing specific legacy image IDs. No global prune runs
+automatically. BuildKit cache is separate and may retain shared layers even after
+an image is removed. Inspect it with `docker buildx du`; opt-in maintenance such
+as `docker buildx prune --filter until=168h` removes old unused cache but can
+affect rebuild speed for other projects using the same builder.
+
 ## Development Guidelines
 
 ### Code Quality Standards

apps/agenstra/backend-agent-controller/package.json

@@ -62,6 +62,7 @@
     "dockerode": {
       "protobufjs": "7.5.5"
     },
+    "proxy-addr": "2.0.8",
     "tar": "7.5.19"
   }
 }

apps/agenstra/backend-agent-controller/project.json

@@ -147,6 +147,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=agenstra-backend-agent-controller"
+          ],
           "tags": ["ghcr.io/forepath/agenstra-controller-api:latest"]
         },
         "release": {
@@ -165,7 +168,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/agenstra/backend-agent-controller",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=agenstra-backend-agent-controller"
       }
     },
     "openapi-client-js": {

apps/agenstra/backend-agent-manager/package.json

@@ -59,6 +59,7 @@
     "dockerode": {
       "protobufjs": "7.5.5"
     },
+    "proxy-addr": "2.0.8",
     "tar": "7.5.19"
   }
 }

apps/agenstra/backend-agent-manager/project.json

@@ -128,6 +128,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=agenstra-backend-agent-manager"
+          ],
           "tags": ["ghcr.io/forepath/agenstra-manager-api:latest"]
         },
         "release": {
@@ -153,6 +156,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=agenstra-backend-agent-manager"
+          ],
           "tags": [
             "registry.forenet.internal/forepath/agenstra-manager-worker:test"
           ]
@@ -173,7 +179,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/agenstra/backend-agent-manager",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=agenstra-backend-agent-manager"
       }
     },
     "openapi-client-js": {

apps/agenstra/frontend-agent-console/project.json

@@ -219,6 +219,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=agenstra-frontend-agent-console"
+          ],
           "tags": ["ghcr.io/forepath/agenstra-console-server:latest"]
         },
         "release": {
@@ -237,7 +240,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/agenstra/frontend-agent-console",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=agenstra-frontend-agent-console"
       }
     },
     "sbom": {

apps/agenstra/frontend-billing-console/project.json

@@ -224,6 +224,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=agenstra-frontend-billing-console"
+          ],
           "tags": ["ghcr.io/forepath/agenstra-billing-console-server:latest"]
         },
         "release": {
@@ -242,7 +245,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/decabill/frontend-billing-console",
-        "command": "BILLING_CONSOLE_SERVER_IMAGE=ghcr.io/forepath/agenstra-billing-console-server:latest BILLING_CONSOLE_SERVER_CONTAINER_NAME=agenstra-billing-console-server docker compose up -d --force-recreate --remove-orphans"
+        "command": "BILLING_CONSOLE_SERVER_IMAGE=ghcr.io/forepath/agenstra-billing-console-server:latest BILLING_CONSOLE_SERVER_CONTAINER_NAME=agenstra-billing-console-server docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=agenstra-frontend-billing-console"
       }
     },
     "sbom": {

apps/agenstra/frontend-docs/project.json

@@ -229,6 +229,7 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": ["io.forepath.one.test-project=agenstra-frontend-docs"],
           "tags": ["ghcr.io/forepath/agenstra-docs-server:latest"]
         },
         "release": {
@@ -247,7 +248,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/shared/frontend-docs",
-        "command": "DOCS_SERVER_IMAGE=ghcr.io/forepath/agenstra-docs-server:latest DOCS_SERVER_CONTAINER_NAME=agenstra-docs-server docker compose up -d --force-recreate --remove-orphans"
+        "command": "DOCS_SERVER_IMAGE=ghcr.io/forepath/agenstra-docs-server:latest DOCS_SERVER_CONTAINER_NAME=agenstra-docs-server docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=agenstra-frontend-docs"
       }
     },
     "sbom": {

apps/agenstra/frontend-landingpage/project.json

@@ -181,6 +181,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=agenstra-frontend-landingpage"
+          ],
           "tags": ["ghcr.io/forepath/agenstra-landingpage-server:latest"]
         },
         "release": {
@@ -199,7 +202,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/agenstra/frontend-landingpage",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=agenstra-frontend-landingpage"
       }
     },
     "sbom": {

apps/agenstra/native-agent-console/package.json

@@ -25,5 +25,8 @@
     "@electron-forge/plugin-auto-unpack-natives": "7.10.2",
     "electron": "39.2.7",
     "electron-builder": "25.1.8"
+  },
+  "overrides": {
+    "proxy-addr": "2.0.8"
   }
 }

apps/decabill/backend-billing-manager/package.json

@@ -65,6 +65,7 @@
     "dockerode": {
       "protobufjs": "7.5.5"
     },
+    "proxy-addr": "2.0.8",
     "tar": "7.5.19"
   }
 }

apps/decabill/backend-billing-manager/project.json

@@ -160,6 +160,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=decabill-backend-billing-manager"
+          ],
           "tags": ["ghcr.io/forepath/decabill-billing-api:latest"]
         },
         "release": {
@@ -178,7 +181,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/decabill/backend-billing-manager",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=decabill-backend-billing-manager"
       }
     },
     "openapi-client-js": {

apps/decabill/frontend-billing-console/project.json

@@ -220,6 +220,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=decabill-frontend-billing-console"
+          ],
           "tags": ["ghcr.io/forepath/decabill-billing-console-server:latest"]
         },
         "release": {
@@ -238,7 +241,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/decabill/frontend-billing-console",
-        "command": "BILLING_CONSOLE_SERVER_IMAGE=ghcr.io/forepath/decabill-billing-console-server:latest BILLING_CONSOLE_SERVER_CONTAINER_NAME=decabill-billing-console-server docker compose up -d --force-recreate --remove-orphans"
+        "command": "BILLING_CONSOLE_SERVER_IMAGE=ghcr.io/forepath/decabill-billing-console-server:latest BILLING_CONSOLE_SERVER_CONTAINER_NAME=decabill-billing-console-server docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=decabill-frontend-billing-console"
       }
     },
     "sbom": {

apps/decabill/frontend-docs/project.json

@@ -219,6 +219,7 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": ["io.forepath.one.test-project=decabill-frontend-docs"],
           "tags": ["ghcr.io/forepath/decabill-docs-server:latest"]
         },
         "release": {
@@ -237,7 +238,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/shared/frontend-docs",
-        "command": "DOCS_SERVER_IMAGE=ghcr.io/forepath/decabill-docs-server:latest DOCS_SERVER_CONTAINER_NAME=decabill-docs-server docker compose up -d --force-recreate --remove-orphans"
+        "command": "DOCS_SERVER_IMAGE=ghcr.io/forepath/decabill-docs-server:latest DOCS_SERVER_CONTAINER_NAME=decabill-docs-server docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=decabill-frontend-docs"
       }
     },
     "sbom": {

apps/decabill/frontend-landingpage/project.json

@@ -182,6 +182,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=decabill-frontend-landingpage"
+          ],
           "tags": ["ghcr.io/forepath/decabill-landingpage-server:latest"]
         },
         "release": {
@@ -200,7 +203,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/decabill/frontend-landingpage",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=decabill-frontend-landingpage"
       }
     },
     "sbom": {

apps/forepath/backend-communication/package.json

@@ -33,5 +33,8 @@
   "devDependencies": {
     "tslib": "2.8.1",
     "typescript": "5.9.3"
+  },
+  "overrides": {
+    "proxy-addr": "2.0.8"
   }
 }

apps/forepath/backend-communication/project.json

@@ -93,6 +93,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=forepath-backend-communication"
+          ],
           "tags": ["ghcr.io/forepath/forepath-communication-api:latest"]
         },
         "release": {
@@ -111,7 +114,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/forepath/backend-communication",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=forepath-backend-communication"
       }
     },
     "openapi-client-js": {

apps/forepath/frontend-billing-console/project.json

@@ -224,6 +224,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=forepath-frontend-billing-console"
+          ],
           "tags": ["ghcr.io/forepath/forepath-billing-console-server:latest"]
         },
         "release": {
@@ -242,7 +245,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/decabill/frontend-billing-console",
-        "command": "BILLING_CONSOLE_SERVER_IMAGE=ghcr.io/forepath/forepath-billing-console-server:latest BILLING_CONSOLE_SERVER_CONTAINER_NAME=forepath-billing-console-server docker compose up -d --force-recreate --remove-orphans"
+        "command": "BILLING_CONSOLE_SERVER_IMAGE=ghcr.io/forepath/forepath-billing-console-server:latest BILLING_CONSOLE_SERVER_CONTAINER_NAME=forepath-billing-console-server docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=forepath-frontend-billing-console"
       }
     },
     "sbom": {

apps/forepath/frontend-landingpage/project.json

@@ -184,6 +184,9 @@
       "configurations": {
         "test": {
           "load": true,
+          "labels": [
+            "io.forepath.one.test-project=forepath-frontend-landingpage"
+          ],
           "tags": ["ghcr.io/forepath/forepath-landingpage-server:latest"]
         },
         "release": {
@@ -202,7 +205,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "apps/forepath/frontend-landingpage",
-        "command": "docker compose up -d --force-recreate --remove-orphans"
+        "command": "docker compose up -d --force-recreate --remove-orphans && docker image prune --force --filter label=io.forepath.one.test-project=forepath-frontend-landingpage"
       }
     }
   }