| 1 | # Docker DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own Docker build contexts and runtime container definitions. |
| 6 | - Keep framework runtime, agent execution runtime, exposed ports, mounted paths, and image build assumptions explicit. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - `base/` owns the base image context. |
| 11 | - `run/` owns the runnable image context and compose file. |
| 12 | - Root `DockerfileLocal` is owned by the root contract but must stay compatible with this directory. |
| 13 | |
| 14 | ## Local Contracts |
| 15 | |
| 16 | - Preserve the two-runtime model: the Python 3.12 framework runtime under `/opt/venv-a0` runs the WebUI, APIs, scheduler, framework imports, and plugin hooks; the Python 3.13 agent execution runtime under `/opt/venv` runs agent terminal tasks and user code. |
| 17 | - Verify backend imports and plugin hooks with `/opt/venv-a0`; packages installed into `/opt/venv` do not prove framework compatibility. |
| 18 | - Do not bake secrets, local `.env` values, or user data into images. |
| 19 | - Keep compose mounts aligned with `usr/` and other runtime-state expectations. |
| 20 | - Image changes that affect GitHub publishing must stay synchronized with `.github/workflows/docker-publish.yml`. |
| 21 | |
| 22 | ## Work Guidance |
| 23 | |
| 24 | - Keep Dockerfile steps cache-friendly and explicit about which runtime they target. |
| 25 | - Avoid broad copies of ignored runtime folders. |
| 26 | - Update setup docs when ports, volumes, startup commands, or runtime layout change. |
| 27 | |
| 28 | ## Verification |
| 29 | |
| 30 | - Build the affected Docker context when Docker behavior changes. |
| 31 | - Run Docker-related tests or startup smoke checks when changing runtime entrypoints. |
| 32 | |
| 33 | ## Child DOX Index |
| 34 | |
| 35 | Direct child DOX files: |
| 36 | |
| 37 | | Child | Scope | |
| 38 | | --- | --- | |
| 39 | | [base/AGENTS.md](base/AGENTS.md) | Base image Dockerfile, copied filesystem, and installation scripts. | |
| 40 | | [run/AGENTS.md](run/AGENTS.md) | Runnable image Dockerfile, compose example, entrypoints, and install scripts. | |