Dockerfile Standards

Container image expectations for Assistance-operated environments

Dockerfiles define what runs inside your containers. Assistance reviews and operates the platform around container images, but the application team remains responsible for what the image contains and how the process behaves unless application engineering is explicitly in scope.

What a production-ready image needs#

Requirement	Why it matters
Reproducible build	CI, rollback, and incident review need known inputs and tags
Minimal runtime	Smaller attack surface, faster pulls, and less patch noise
Non-root process	Reduces impact if the application is compromised
Health and shutdown behavior	Enables safe restarts, rollouts, autoscaling, and incident triage
Externalized configuration	Avoids rebuilding images for environment-specific settings
Clear ownership	Someone must approve dependency, base-image, and vulnerability changes

What Assistance operates#

Area	Assistance responsibility
Review	Dockerfile and image workflow review for managed environments
Registry integration	repository layout, tag conventions, promotion rules, retention, and pull credentials where scoped
Security workflow	scanning integration, base-image refresh guidance, and exception tracking where scoped
Runtime fit	resource requests, exposed ports, health checks, volume assumptions, and deployment target compatibility
Change process	planned base-image or runtime changes, rollback notes, and production validation checks

What the customer owns#

Area	Customer responsibility
Application code	correctness, tests, startup behavior, graceful shutdown, and dependency compatibility
Base image choice	language/runtime version, license acceptance, and upgrade timing unless delegated
Vulnerability remediation	fixes, risk acceptance, and release approval for image contents
Secrets and config	no secrets in images, correct environment variables, and safe application consumption
Build pipeline	source provenance, build triggers, and release promotion unless CI/CD operation is in scope

Do not bake secrets into images

Secrets, certificates, tokens, and customer data must be delivered through the agreed secret-management mechanism. Images should be safe to store in the configured registry and cache layers.

Assistance review checklist#

pinned or intentionally managed base image
deterministic dependency installation
multi-stage build where it materially reduces risk or size
non-root runtime user where compatible
no secret material copied into layers
explicit ports and runtime command
health endpoint or documented readiness behavior
log output suitable for the platform collector
known persistent paths, if any
documented owner for vulnerability and dependency changes

Change workflow#

Request review when changing language runtime versions, base images, package managers, exposed ports, persistent paths, health checks, or build secrets. Emergency changes may be needed for actively exploited vulnerabilities, but Assistance still needs validation evidence before promoting the image into a managed production environment.

Not included by default#

rewriting application build systems
fixing application dependency conflicts
owning license/compliance decisions for packages in the image
guaranteeing performance for images that bypass review
accepting images without an owner and rollback path

Getting started#

Share the Dockerfile, build pipeline, registry target, deployment target, and current security or reliability concerns. Assistance will review the image path and define the operating boundary.

Request container review →