> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Operating System Packages in a CockroachDB Docker Image

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

This page shows how to build a CockroachDB Docker image that includes operating system (OS) package updates released after Cockroach Labs published the image.

Each [CockroachDB Docker image](https://hub.docker.com/r/cockroachdb/cockroach) includes the latest OS packages that were available when the release was published. Fixes that the OS vendor releases later reach the official images with the next CockroachDB patch release. To pick up a fix sooner, for example when a vulnerability scanner reports a fixable vulnerability in an OS package, build an image on top of the official image and upgrade its packages. This is the same step Cockroach Labs runs when it publishes an image. The rebuilt image contains the same CockroachDB binary as the official image; only the OS packages change.

CockroachDB Docker images are available in the following variants:

| Variant | Base image | Tag format | Package manager |
| - | - | - | - |
| Default | Red Hat Universal Base Image 10 (UBI) minimal | `{version}`, `{version}-fips` | `microdnf` |
| Ubuntu (experimental) | Ubuntu 24.04 LTS | `{version}-noble` | `apt-get` |

The `-noble` image is available starting in v26.2.7. Experimental images are not qualified for production use and not eligible for support or uptime SLA commitments.

<Note>
  Avoid upgrading packages inside running containers. Changes made to a running container are lost when the container is recreated, are not visible to scanners that inspect the image in your registry, and can leave nodes running different package versions.
</Note>

## Before you begin

* Install [Docker](https://docs.docker.com/get-started/get-docker/). To build images for more than one platform, you also need [Docker Buildx](https://docs.docker.com/build/building/multi-platform/).
* Make sure the build host can reach Docker Hub and the OS vendor's package repositories: the Red Hat UBI repositories for the default image, or the Ubuntu archive for the `-noble` image.
* Have access to a container registry where you can push the rebuilt image.

## Step 1. Create a Dockerfile

Create a directory for the build, and in it create a file named `Dockerfile` with the contents for the image variant you use.

### Default (UBI) images

For the default image and the FIPS-ready image, create the following `Dockerfile`:

```dockerfile theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
FROM cockroachdb/cockroach:{tag}
RUN microdnf -y --best --refresh upgrade && microdnf clean all && rm -rf /var/cache/yum
```

Replace `{tag}` with the tag of the image to update, for example `v26.2.7` or `v26.2.7-fips`.

If `microdnf` fails with a dependency error, the Red Hat UBI package repositories are probably partway through publishing an update, and some related packages are not available yet. Retry the build later.

### `-noble` images

For the `-noble` image, create the following `Dockerfile`:

```dockerfile theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
FROM cockroachdb/cockroach:{version}-noble
RUN apt-get update && apt-get upgrade -y && apt-get clean && rm -rf /var/lib/apt/lists/*
```

Replace `{version}` with the CockroachDB version of the image to update, for example `v26.2.7`.

<Tip>
  To make the build reproducible, reference the base image by its digest rather than only by its tag, for example `FROM cockroachdb/cockroach:v26.2.7@sha256:{digest}`. To look up the digest of an image, run `docker buildx imagetools inspect cockroachdb/cockroach:{tag}`.
</Tip>

## Step 2. Build the image

To build the image for the platform of the build host, run the following command from the directory that contains the `Dockerfile`:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
docker build --pull --no-cache --load --tag {image} .
```

Replace `{image}` with the registry, repository, and tag for the rebuilt image, for example `registry.example.com/cockroach:v26.2.7-20261006`. Cockroach Labs recommends giving each rebuild a new tag rather than reusing a tag, so that you can tell rebuilt images apart and roll back to an earlier one.

The `--no-cache` flag is required. Without it, Docker can reuse the package upgrade layer from an earlier build, and the image does not receive packages released since then. The `--load` flag makes the image available to the local Docker engine for the next steps, including when the build runs in a separate builder container.

To build a multi-platform image, use `docker buildx build` instead. This command pushes the image to your registry directly, so skip [Step 4](#step-4-push-the-image):

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
docker buildx build --pull --no-cache --platform {platforms} --tag {image} --push .
```

Replace `{platforms}` with a comma-separated list of the platforms you deploy on. The default image is available for `linux/amd64`, `linux/arm64`, and `linux/s390x`. The FIPS-ready image is available for `linux/amd64`. The `-noble` image is available for `linux/amd64` and `linux/arm64`. Building for a platform other than the build host's requires emulation or a multi-node builder. Refer to [Multi-platform builds](https://docs.docker.com/build/building/multi-platform/) in the Docker documentation.

## Step 3. Verify the image

To confirm that the rebuilt image starts and contains the expected CockroachDB version, run:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
docker run --rm {image} version
```

The output includes the following:

```
Build Tag:        v26.2.7
...
Build Type:       release
```

The `Build Tag` value must match the CockroachDB version of the image you updated. Then scan the rebuilt image with your vulnerability scanner to confirm that the packages were updated.

## Step 4. Push the image

To push the rebuilt image to your registry, run:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
docker push {image}
```

## Step 5. Deploy the image

Replace the official image with the rebuilt image in your deployment configuration, such as the image field of your Kubernetes manifest or your container runtime's run command. Because the CockroachDB version does not change, no <InternalLink path="upgrade-cockroach-version">version upgrade</InternalLink> or finalization is involved.

Restart one node at a time on the new image so that the cluster remains available. Refer to <InternalLink path="node-shutdown#stop-and-restart-a-node">Stop and restart a node</InternalLink>.

## See also

* [Install CockroachDB on Linux](install-cockroachdb-linux)
* [Install a FIPS-ready CockroachDB Runtime](fips)
* [Node Shutdown](node-shutdown)
* [Production Checklist](recommended-production-settings)