container-scaffold
The services a project runs on are part of its architecture: the ADL names
the external systems (a database, a broker, a cache) and the components
that talk to them. Once the architecture scaffold is committed, lay down
what runs them locally, so that the integration session finds them ready.
No business logic: the application's entrypoint is the module the ADL
names, which may still be an interface.
When
- The ADL has an external system that runs as a service, or the shopping
list asks for a Dockerfile or compose.
- After the architecture scaffold (
adl-scaffold) and before the
interfaces: the interfaces of the components that talk to a service read
its settings as compose passes them.
Ask the user only what the shopping list leaves open: the service images
and versions (propose the current stable major), the port the application
listens on, how it is started.
What to write
In the project's directory (the folder, for a project in a folder of a
repository):
Dockerfile: the application only, built from the lock file, no
development dependencies, running as a non-root user. Python with uv:
FROM python:<version>-slim
COPY --from=ghcr.io/astral-sh/uv:<uv version> /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project
COPY src ./src
RUN uv sync --frozen --no-dev
RUN useradd --create-home app
USER app
ENV PATH="/app/.venv/bin:$PATH"
CMD [<the command that starts the application>]
.dockerignore: .git, .venv, the caches, tests/, .sources/,
.documentation/.
compose.yaml: one service for the application (build: .) and one
per service in the ADL. Each service with a healthcheck (Postgres:
pg_isready); the application depends_on them with condition: service_healthy; data in a named volume. The application reads every
setting from the environment (a DATABASE_URL, not host, port and name
apart); compose sets development values, never real secrets.
Makefile targets: up (docker compose up --build -d), down
(docker compose down), logs. Leave the existing targets as they are.
CI of a project in a folder: its workflow at the repository's root
(.github/workflows/<folder>.yml) runs only on changes to the folder and
to itself: paths: ["<folder>/**", ".github/workflows/<folder>.yml"]
under both push and pull_request. The scaffold writes it so; add it
when an older workflow lacks it.
The tests do not use compose: integration tests start their own services
(testcontainers, or what the handbook says), so they run the same in CI.
That harness is not part of this scaffold: unclebob writes it test-first,
in the first unit whose red needs the service, and refactors it as it grows.
Check and commit
toolchain build still passes, and the architecture tests too.
- Commit with
linus commit --phase architecture as build(<scope>): …,
the Dockerfile, .dockerignore, compose and Makefile in one commit, the
CI filter in its own ci(<scope>): ….
- Report the files in
FORD_DONE (the services, their images, the settings
the application reads), so that kent passes them to unclebob for the
integration session.
1---2name: container-scaffold3description: The project's runtime infrastructure, laid by ford after the architecture scaffold - a Dockerfile for the application, compose.yaml with the services the ADL names (a database, a broker), .dockerignore, the Makefile targets to run them, and the CI's path filter for a project in a folder. Load it in ford's target mode when the ADL has an external system that runs as a service, or the shopping list asks for containers.4metadata:5 source: https://skillmd.com/skills/korsmakolnikov/container-scaffold6---78# container-scaffold910The services a project runs on are part of its architecture: the ADL names11the external systems (a database, a broker, a cache) and the components12that talk to them. Once the architecture scaffold is committed, lay down13what runs them locally, so that the integration session finds them ready.14No business logic: the application's entrypoint is the module the ADL15names, which may still be an interface.1617## When1819* The ADL has an external system that runs as a service, or the shopping20 list asks for a Dockerfile or compose.21* After the architecture scaffold (`adl-scaffold`) and before the22 interfaces: the interfaces of the components that talk to a service read23 its settings as compose passes them.2425Ask the user only what the shopping list leaves open: the service images26and versions (propose the current stable major), the port the application27listens on, how it is started.2829## What to write3031In the project's directory (the folder, for a project in a folder of a32repository):3334* **`Dockerfile`**: the application only, built from the lock file, no35 development dependencies, running as a non-root user. Python with uv:3637 ```dockerfile38 FROM python:<version>-slim39 COPY --from=ghcr.io/astral-sh/uv:<uv version> /uv /usr/local/bin/uv40 WORKDIR /app41 COPY pyproject.toml uv.lock ./42 RUN uv sync --frozen --no-dev --no-install-project43 COPY src ./src44 RUN uv sync --frozen --no-dev45 RUN useradd --create-home app46 USER app47 ENV PATH="/app/.venv/bin:$PATH"48 CMD [<the command that starts the application>]49 ```5051* **`.dockerignore`**: `.git`, `.venv`, the caches, `tests/`, `.sources/`,52 `.documentation/`.53* **`compose.yaml`**: one service for the application (`build: .`) and one54 per service in the ADL. Each service with a `healthcheck` (Postgres:55 `pg_isready`); the application `depends_on` them with `condition:56 service_healthy`; data in a named volume. The application reads every57 setting from the environment (a `DATABASE_URL`, not host, port and name58 apart); compose sets development values, never real secrets.59* **Makefile targets**: `up` (`docker compose up --build -d`), `down`60 (`docker compose down`), `logs`. Leave the existing targets as they are.61* **CI of a project in a folder**: its workflow at the repository's root62 (`.github/workflows/<folder>.yml`) runs only on changes to the folder and63 to itself: `paths: ["<folder>/**", ".github/workflows/<folder>.yml"]`64 under both `push` and `pull_request`. The scaffold writes it so; add it65 when an older workflow lacks it.6667The tests do not use compose: integration tests start their own services68(testcontainers, or what the handbook says), so they run the same in CI.69That harness is not part of this scaffold: unclebob writes it test-first,70in the first unit whose red needs the service, and refactors it as it grows.7172## Check and commit7374* `toolchain build` still passes, and the architecture tests too.75* Commit with `linus commit --phase architecture` as `build(<scope>): …`,76 the Dockerfile, `.dockerignore`, compose and Makefile in one commit, the77 CI filter in its own `ci(<scope>): …`.78* Report the files in `FORD_DONE` (the services, their images, the settings79 the application reads), so that kent passes them to unclebob for the80 integration session.