# Containers and Deployment Guidelines

## Docker/Podman basics

- Prefer small, focused images with:
  - minimal base (e.g. `python:3.x-slim`, `debian:stable-slim`, or distroless where appropriate)
  - pinned major versions for reproducibility.
- Use multi-stage builds:
  - builder image for dependencies and compilation
  - slim runtime image with only what is needed.

## Image structure

- Avoid copying whole repositories blindly; copy only necessary parts:
  - `pyproject.toml` / `setup.cfg` / `requirements.txt`
  - `src/` or application code
  - scripts and entrypoints.
- Do not run containers as root unless strictly required.
- Set a working directory (`WORKDIR /app`) and explicit entrypoint.

## Dependencies and caching

- Leverage Docker layer caching:
  - copy dependency descriptors first
  - install dependencies
  - then copy source code.
- Pin versions of critical dependencies; use constraints files where relevant.

## Runtime behavior

- Applications should respond correctly to signals (`SIGTERM`, `SIGINT`) and exit promptly.
- Avoid writing to container filesystem except to designated writable paths; support external volumes for state.
- Expose configuration via env vars with sane defaults.

## Observability and health

- Provide:
  - health endpoints for HTTP services
  - metrics endpoints (Prometheus-style when building web services).
- Log to stdout/stderr in structured or easily parseable format.
- Make it easy to run the same container locally and in CI/CD.

## Security basics

- Minimize attack surface:
  - remove build tools, compilers, and unnecessary packages in runtime image
  - use non-root user
  - keep base images updated.
- Handle secrets via env vars or secret stores, never bake them into images.