Contributing Docker guide

This guide covers the Docker development workflow for contributors who need to modify Dockerfiles, add dependencies, or debug container issues.

Prerequisites

Quick reference

# Build all images
docker compose build

# Build a single service
docker compose build platform

# Run container smoke tests (non-conflicting ports)
bun run docker:test

# Validate image structure (no secrets, OCI labels, size budgets)
bun run docker:test:image

# Vulnerability scan (requires trivy)
bun run docker:test:vulnerability

# Local development with hot-reload
docker compose -f compose.yml -f compose.dev.yml up --build

Dockerfile conventions

Multi-stage builds

All Python and Node.js images use multi-stage builds. The pattern is:

1. Builder stage — Install all build dependencies, compile native packages
2. Runtime stage — Copy only runtime artifacts into a clean base image
3. Squash stage — FROM scratch + COPY --from=runtime / / to flatten layers

The squash stage ensures that file deletions in cleanup steps actually reclaim disk space, rather than just adding masking layers. This keeps build tools (gcc, build-essential, libpq-dev) out of the final image.

Important: When using FROM scratch, all ENV vars from upstream stages are lost and must be re-declared. Volume mountpoints must also be pre-created in the runtime stage before the squash.

Layer caching

Order your COPY and RUN instructions from least-frequently-changed to most-frequently-changed:

# Good: dependencies change less often than application code
COPY pyproject.toml .
RUN uv pip install --system --no-cache-dir .
COPY app/ ./app/

No cache flags

Always use --no-cache-dir (pip/uv) and --no-install-recommends (apt-get):

RUN apt-get update && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*
RUN uv pip install --system --no-cache-dir .

OCI labels

Every Dockerfile must include a version label:

ARG VERSION=dev
LABEL org.opencontainers.image.version="${VERSION}"

Health checks

Every Dockerfile must include a HEALTHCHECK instruction:

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:8001/health || exit 1

Image size budgets

Each image has a size budget. CI will fail if an image exceeds its budget.

Common reasons for size increases

1. Adding a new Python dependency — Check if it pulls in large transitive deps
2. Adding apt packages — Use --no-install-recommends and clean up afterwards
3. Forgetting to strip in builder — Remove __pycache__, .pyc, test dirs, .so debug symbols
4. Not using multi-stage — Build tools must stay in the builder stage

Reducing image size

# Check what's taking space in an image
docker run --rm -it <image> du -sh /* 2>/dev/null | sort -rh | head -20

# Check Python packages
docker run --rm <image> pip list 2>/dev/null || \
docker run --rm <image> python -c "import pkg_resources; [print(f'{p.key}: {p.location}') for p in pkg_resources.working_set]"

# Dive: visual layer analysis
# Install: https://github.com/wagoodman/dive
dive <image>

Testing workflow

1. Build and smoke test

bun run docker:test

This runs tests/container-smoke-test.sh which:

• Builds all 5 images
• Starts services on non-conflicting ports (15432, 18001, 18002, etc.)
• Waits for health checks
• Validates HTTP endpoints
• Tests inter-service connectivity
• Tears down everything (including volumes)

2. Image validation

bun run docker:test:image

Checks each image for:

• OCI org.opencontainers.image.version label
• Non-root user (required for platform)
• No secrets baked into image env or filesystem
• HEALTHCHECK instruction present
• Image size within budget

3. Vulnerability scanning

bun run docker:test:vulnerability

Runs Trivy against each image. Reports are saved to trivy-reports/.

To suppress a known false positive, add the CVE ID to .trivyignore:

CVE-2023-12345    # false positive: function not reachable

CI/CD pipeline

On pull requests (build.yml)

On release tags (release.yml)

The container test gate pulls the just-pushed images and runs smoke tests + image validation before manifests are created.

Common pitfalls

"parent snapshot does not exist"

Docker BuildKit cache corruption. Fix:

docker builder prune -f

Port already in use

Use compose.test.yml which maps to non-conflicting ports:

docker compose -f compose.yml -f compose.test.yml --env-file .env.test -p tale-test up -d

Python package not found at runtime

If a package is installed in the builder but not available in the runtime stage, check that:

1. You're copying from the correct path: COPY --from=builder /usr/local/lib/python3.11/site-packages ...
2. The package's .dist-info isn't being removed if something depends on metadata at runtime
3. The strip step isn't removing required .so files

Node.js module not found at runtime

If a module is missing after the pruner stage, check:

1. Whether it's listed in dependencies (not devDependencies) in package.json
2. Whether the pruner step explicitly removes it in the rm -rf list