Skip to content

Building Images in Coherence: Options and Best Practices

Coherence offers multiple ways to build and manage container images for your services. This guide outlines the different options available, their benefits, and how to implement them.

This is the easiest and most integrated option, leveraging Coherence's built-in build pipeline.

How it works:

  • Builds occur in your connected cloud account as part of the Coherence build pipeline.
  • Utilizes best practices like multi-stage Docker build cache.
  • Uses a managed registry in the same cloud, reducing vendor complexity.
  • Offers automatic containerization with Nixpacks if no Dockerfile is defined for the service.
    • You can configure the Dockerfile, docker build context, or Nixpacks configuration options when setting up the service, and optionally by including the necessary config files in your repo.
    • For Nixpacks, you can also use environment variable configuration options to define behavior. See Nixpacks docs for more details.

To use this option:

  • In your service configuration, choose "repo" as the container source.
  • Coherence will automatically set up the build pipeline in your cloud account.

Benefits:

  • Seamless integration with Coherence's workflow.
  • Optimized for performance and security.
  • Reduces complexity and the number of vendors in your stack by using cloud-native services.

2. Using Externally Built Images

This option allows you to use pre-built images, either public or private.

Types of external images:

  • Public images (e.g., open-source projects on Docker Hub)
  • Images built in your external CI/CD pipeline
  • Manually pushed images to a private registry

To use this option:

  • In your service configuration, choose "existing image" as the container source.
  • Select one of the following tag options:
    • "Static": Uses the same tag on every deploy until manually updated in the service config form or cnc.yml. Best for deploying 3rd party built containers.
    • "GitHub": Uses the SHA from the repo push to GitHub as the image tag.
    • "Other": Allows you to specify a custom tag for each deploy via the new build form or CLI.

Considerations:

  • It's easiest to use the Coherence-managed registry in AWS/GCP for each collection.
    • If you've already had at least one successful provision task for your collection, the managed registry URL will be shown in the service edit form. You should use this value as the image host for your image source. You'll copy the managed image registry URL into the Image form field to configure your service. other-container-source-mode
    • If you haven't yet provisioned, you'll need to use a placeholder value until you provision the infra (which creates the registry) and then you will need to come back and edit the service to deploy from that image instead of your placeholder. You only need to provision once per collection to complete this step.
    • You'll need to set up your image build script to push the built images to this registry with the appropriate tags. Popular CI systems have plenty of examples of pushing to ECR in AWS or Artifact Registry in GCP, but please let us know if you need any help here!
  • You can use another registry in the same cloud if service credentials are authorized.
    • Using external registries may require CNC customization for authentication to pull the images. This is not yet a first-class supported feature in Coherence.

Benefits:

  • Flexibility to integrate with existing build processes.
  • Can use images built on other platforms (e.g., GitLab, Bitbucket) for managed infra and deploy pipelines using the CLI from a CI provider.
  • Allows for manual control over image versions.
  • Build speed can be higher in some well-designed pipelines or services, especially when using a persistent disk for caching Docker layers between builds.

Examples

  • "Static" tag option:
    • Service config: image set to myimage, tag set to v1.0-ubuntu
    • Result: Every pipeline deploys myimage:v1.0-ubuntu
  • "GitHub" tag option:
    • Service config: image set to us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api
    • Result: On each push, deploys us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api:GIT_PUSH_SHA
    • Note: New build form uses the provided commit SHA from the branch as the tag
  • "Other" tag option:
    • Service config: image set to us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api
    • Result: Uses the tag provided in the new build form or CLI for each deployment, like us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api:PROVIDED_TAG
    • Note: Branch is not used in this configuration in either the UI or CLI

3. CNC Template Customization

For advanced use cases, you can modify the build step using CNC template customization.

How it works:

  • Augment or replace the default Coherence build script that runs in the CI pipeline. See examples of cnc customization here.
  • Customize the build process while still leveraging Coherence's environment management and script templating framework.

To use this option:

  1. Configure the app's cnc customization template location in the app's settings page in the Coherence dashboard.
  2. Modify the CNC build template for your service. Implement custom build logic using tools like Depot or Docker Build Cloud.
  3. Use the CNC template variables to access Coherence system information (e.g., environment name, service image tag).
  4. Your builds will now use your custom script rather than the included one in your cnc flavor.

Benefits:

  • Maximum flexibility in build process.
  • Can integrate specialized build tools or workflows.
  • Maintains connection with Coherence's environment and deployment management.

Choosing the Right Option

  • For most users: The built-in build step (Option 1) provides the best balance of ease-of-use and integration.
  • For teams with existing CI/CD: Using externally built images (Option 2) allows you to maintain your current build process while leveraging Coherence for deployment.
  • For advanced customization: CNC template customization (Option 3) offers the most flexibility but requires more setup and maintenance.

Remember, regardless of the build method chosen, Coherence continues to manage your environment infrastructure and deployment pipelines, ensuring consistency across your application lifecycle.