A production Docker image should contain only what the application needs to run, be reproducible from version-controlled inputs, and provide enough information for your deployment platform to operate it safely. This checklist covers multi-stage builds, base-image choices, caching, non-root execution, health checks, vulnerability scanning, and release verification for Node.js, Python, and static frontend services.
Overview
A Dockerfile is a build recipe, not just a startup command. A reliable production image separates compilation from runtime, pins important inputs, excludes development files, and makes configuration explicit. The goal is not always the smallest possible image. The better target is the smallest image that remains understandable, supportable, compatible with the application, and straightforward to scan.
Start by identifying the service type:
- Compiled or bundled application: build dependencies belong in a builder stage; the runtime stage should receive only the compiled output and production dependencies.
- Interpreted application: install only runtime dependencies and keep build tools, test fixtures, caches, and source-control metadata out of the final image.
- Static frontend: build the application in Node.js or another toolchain image, then serve the generated files with a small web server image or your platform’s static hosting layer.
Use an explicit base-image policy. A versioned tag makes intent clearer than an unqualified tag, while a digest can provide stronger reproducibility when your update process is prepared to refresh it. Treat runtime versions, operating-system packages, and lockfiles as release inputs that need planned updates rather than accidental changes during a build.
Base-image decision table
| Image family | Useful when | Trade-offs to check |
|---|---|---|
| Distroless | The application has a stable runtime and you want very few tools and files in production. | Interactive debugging is limited; confirm certificates, timezone data, users, and startup behavior are available. |
| Slim | You want a reduced general-purpose distribution with familiar package and debugging conventions. | It may be larger than a minimal image, and build-time packages must still be kept out of the runtime stage. |
| Alpine | Your application and native dependencies are tested against its C library and package ecosystem. | Native modules and binary compatibility can require extra verification; do not choose it solely because the image appears small. |
| Full distribution | Compatibility, troubleshooting, or a complex system dependency matters more than minimum size. | The image usually contains more packages and a larger attack surface, so remove unnecessary components and scan it regularly. |
Checklist by scenario
Node.js service
Copy the manifest and lockfile before application source so dependency installation can use the Docker layer cache. Use the package manager’s lockfile-aware, production-oriented install mode, and make sure the command matches the lockfile generated by the project.
# syntax=docker/dockerfile:1
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD node -e "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
CMD ["node", "dist/server.js"]
Adjust the output directory, start command, health endpoint, and runtime version to your application. If the service has native modules, test the chosen base image in CI rather than assuming that a smaller distribution will be compatible.
Python service
Use a builder stage when wheels or system packages are needed during installation. A virtual environment gives the runtime stage a clear artifact to copy and helps prevent build-only packages from following the application into production.
FROM python:3.12-slim AS build
WORKDIR /app
ENV VIRTUAL_ENV=/opt/venv
RUN python -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
FROM python:3.12-slim AS runtime
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PATH="/opt/venv/bin:$PATH"
COPY --from=build /opt/venv /opt/venv
COPY --from=build /app ./
RUN useradd --create-home --uid 10001 appuser
USER appuser
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"
CMD ["python", "-m", "your_app"]
For projects using a different dependency manager, preserve its lockfile and use its documented frozen or locked installation mode. Native Python packages may require operating-system libraries in the builder and runtime stages; document those requirements rather than hiding them in an ad hoc build command.
Static frontend service
Static assets should not require Node.js at runtime. Build them in one stage and copy only the output directory to the serving image.
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM nginx:stable-alpine AS runtime
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD wget -q -O /dev/null http://127.0.0.1/ || exit 1
Replace dist with the actual build output. Keep environment-specific values out of the image when they need to change between deployments; use the hosting platform’s runtime configuration or a deliberate configuration-generation step.
Every production image
- Add a
.dockerignorefile that excludes.git, local dependencies, test output, logs, environment files, editor settings, and build artifacts that are recreated inside the image. - Run as a non-root user. Prefer a user supplied by the base image or create a dedicated numeric user in the runtime stage.
- Use exec-form
CMDorENTRYPOINTso the application receives signals directly. - Expose only the port the service actually listens on; remember that
EXPOSEdocuments intent and does not publish a port by itself. - Provide a lightweight health endpoint or command that checks application readiness without depending on external systems.
- Pass secrets at deployment time. Do not copy secret files into an image or place credentials in build arguments, which can remain visible in build history or metadata.
What to double-check
Build speed and layer caching
Order Dockerfile instructions from relatively stable to frequently changing. Copy dependency manifests and install dependencies before copying the complete source tree. Combine related cleanup with the installation command so package caches do not remain in an earlier layer. In CI, configure a cache strategy appropriate to your builder, but never let a cache replace a lockfile or a clean reproducibility check.
Use multi-stage builds for compilation, test tooling, documentation generators, and asset bundlers. The final stage should be assembled deliberately rather than inheriting the builder wholesale. Confirm this by inspecting the image contents and comparing the runtime dependency list with the application’s actual imports or binaries.
Scanning and provenance
Scan the image after it is built, using the vulnerability scanner supported by your team or registry. Scanner results differ in database timing, language-package detection, and severity interpretation, so define a repeatable policy: which findings block a release, which require remediation tickets, and how exceptions expire. Review the base image, operating-system packages, application lockfile, and embedded binaries together.
Where your delivery system supports it, retain the immutable image reference, build logs, source revision, and scan result with the release record. Build the same commit in a clean environment periodically to detect hidden reliance on a developer workstation or an old cache.
Runtime configuration and operations
- Verify that the process binds to the interface and port expected by the platform.
- Set a graceful shutdown strategy and confirm the application handles termination signals.
- Separate liveness from readiness when the platform supports both; a process can be alive while still waiting for startup work.
- Test logs in the deployment environment and write them to standard output and standard error unless a deliberate collector requires another design.
- Check that certificates, locale data, timezone data, temporary directories, and writable paths required by the application exist in the selected runtime image.
Common mistakes
- Using a floating base tag without an update process. It can make two builds differ unexpectedly. Use a documented version policy and refresh images intentionally.
- Copying the entire repository before installing dependencies. A one-line source change can invalidate a costly dependency layer. Copy manifests first.
- Running the builder as the production image. Compilers, test tools, source maps, package caches, and credentials can remain unnecessarily exposed. Use a runtime stage.
- Choosing Alpine by habit. Validate native modules, libc expectations, debugging procedures, and operational tooling before adopting it.
- Treating a passing build as a secure image. A build confirms that commands completed; it does not confirm that dependencies are current, secrets are absent, or vulnerabilities are acceptable.
- Making health checks too expensive or dependent on external services. Health checks run repeatedly. Keep them fast, deterministic, and aligned with the signal the orchestrator needs.
- Hardcoding deployment configuration. Image contents should be reusable across environments. Supply environment-specific values through the deployment system and validate required variables at startup.
When to revisit
Revisit this checklist before a production launch, during planned dependency or runtime upgrades, after a security advisory, and whenever image size or startup time changes unexpectedly. It also belongs in recurring seasonal planning cycles and whenever your build, registry, deployment platform, or vulnerability-scanning workflow changes.
Before each release, confirm the following:
- The runtime and base-image tags or digests follow the current project policy.
- Dependency lockfiles are present, installations are reproducible, and stale packages have an owner and update plan.
- The final image contains no source-control metadata, local environment files, unnecessary development tools, or credentials.
- The service runs as non-root, receives termination signals correctly, and passes its health check in a clean deployment.
- The image has been scanned, findings have been assessed, and any exception has a documented reason and review date.
- Runtime configuration, certificates, writable paths, ports, logs, and rollback references have been tested.
Keep the Dockerfile, .dockerignore, scan policy, and release checklist together in the repository. When an upgrade or incident reveals a new requirement, update those files and the team’s build documentation at the same time. That turns production image maintenance from a one-off optimization exercise into a repeatable cloud deployment workflow.