Skip to content

Unified vs. Per-Environment Docker Images

When building your application, CAP supports two different strategies for how your Docker images are created and tagged. The strategy you choose depends on your application's build process and dependencies. You can configure this using the pipeline.unifiedImage flag.

Unified Images (Default)

By default (pipeline.unifiedImage: true), CAP builds a single Docker image that is promoted through all environments.

  • How it works: A single image is built once at the beginning of the pipeline. This exact same image is then deployed to staging, acceptance, and production. The only change between environments is that the image is re-tagged with the appropriate environment or version tag during the release step.
  • When to use it: This is ideal for compiled applications (like Go or Rust) or static front-end applications (like React, Vue, Angular) where the build artifact is self-contained and does not differ between environments. It provides a strong guarantee that what you test in staging is bit-for-bit identical to what you deploy in production.
pipeline:
  unifiedImage: true

Per-Environment Images

When you set pipeline.unifiedImage: false, CAP builds a unique Docker image for each environment (staging, production, etc.).

  • How it works: A new image is built during the pipeline for each environment. This means the image used for staging is different from the image used for production.
  • When to use it: This is the best approach for applications that have different build-time dependencies for different environments. A common example is a static front-end applications (like React, Vue, Angular) where the build artifact are not self-contained and does differ between environments. 
pipeline:
  unifiedImage: false

Note

When unifiedImage is disabled, all environment variables you define in your config.cap.yaml are automatically made available during the build process.