Docker Outputs

Introduction to Docker Caching

Many real-world CI/CD pipelines don’t just produce files or directories but package entire applications into Docker images. Building Docker images can be time-consuming, especially for large applications, making them perfect candidates for caching.

Grog can cache Docker images, allowing you to:

• Skip building images when their inputs haven’t changed
• Share images between team members using a remote cache
• Integrate Docker builds into your dependency graph
• Push images to registries only when needed

This guide covers how to set up Docker caching, configure storage backends, and define Docker outputs in your build targets.

Setting Up Docker Caching

Choose a Storage Backend

Grog supports two storage backends for Docker images:

Filesystem Backend (Default)

The filesystem backend stores Docker images as content-addressable blobs (manifest, config, and layers) using your configured (remote) filesystem cache:

[docker]
backend = "tarball"  # This is the default, so it's optional

Advantages:

• Simple to set up
• Works with any filesystem cache
• No additional infrastructure required
• Layers and manifests are deduplicated across images, reducing cache size

Disadvantages:

• Loading still streams layers back into the Docker daemon locally

Registry Backend

Note

To use the registry backend you need to have docker installed on your machine.

The registry backend stores Docker images in a Docker registry:

[docker]
backend = "registry"
registry_url = "https://your-registry-url"

Advantages:

• More efficient storage through layer deduplication
• Better performance for large images
• Familiar workflow for Docker users

Disadvantages:

• Requires a registry to be running and accessible
• Requires docker to be installed on your machine
• Needs authentication setup

3. Registry Authentication

When using the registry backend, Grog expects your current session to be authenticated with the registry. Here’s how to authenticate with common registries:

• Docker Hub: Use docker login
• Google Artifact Registry: Follow the GCP authentication docs
• AWS ECR: Follow the AWS ECR authentication docs
• GitHub Container Registry: Use docker login ghcr.io

Note

For CI environments, you’ll need to ensure authentication happens as part of your CI pipeline before Grog runs.

Defining Docker Outputs

Once your Docker storage is set up, you can define Docker image outputs for your targets:

targets:
  - name: build_api_image
    inputs:
      - Dockerfile
      - src/**/*.go
      - go.mod
      - go.sum
    command: |
      # Build the Docker image
      docker build -t api-service:latest .
    outputs:
      # Cache the local image
      - docker::api-service:latest

Using Docker Images in Dependent Targets

You can use Docker images built by one target in dependent targets:

targets:
  - name: build_api_image
    inputs:
      - Dockerfile
      - src/**/*.go
    command: docker build -t api-service:latest .
    outputs:
      - docker::api-service:latest

  - name: integration_test
    dependencies:
      - :build_api_image
    command: |
      # The api-service image is now available locally
      docker run --rm api-service:latest --version
      # Run tests against the image
      go test -tags=integration ./tests/...

Multi-platform Docker Images

For building multi-platform Docker images, see the Multi-platform Builds guide.