Download the Container Images

This guide explains how to download pre-built Dioptra container images from the GitHub Container Registry (GHCR) and verify their authenticity. After completing these steps, you will have container images ready for deployment.

Note

See the Glossary for the meaning of the acronyms used in this guide.

Prerequisites

• Docker Engine installed and running

• A terminal with access to Docker commands

• (Optional) cosign installed for image verification

• (Optional) jq for easier key path retrieval

Downloading the Images

Dioptra images are tagged based on release versions and branches. Choose the appropriate tag for your use case:

• Release tags (e.g., 1.0.0): Stable releases recommended for production use

• Branch tags (e.g., dev): Latest development builds

Replace $TAG with your chosen tag in the commands below or set the TAG environment variable to your chosen value.

Step 1: Pull the Core Images

Open a terminal and pull the core Dioptra images:

docker pull ghcr.io/usnistgov/dioptra/nginx:$TAG
docker pull ghcr.io/usnistgov/dioptra/mlflow-tracking:$TAG
docker pull ghcr.io/usnistgov/dioptra/restapi:$TAG

Step 2: Pull Worker Images

Pull one or more worker images depending on your needs.

CPU workers:

docker pull ghcr.io/usnistgov/dioptra/pytorch-cpu:$TAG
docker pull ghcr.io/usnistgov/dioptra/tensorflow2-cpu:$TAG

GPU workers (optional):

docker pull ghcr.io/usnistgov/dioptra/pytorch-gpu:$TAG
docker pull ghcr.io/usnistgov/dioptra/tensorflow2-gpu:$TAG

Step 3: Verify the Images Exist Locally

Run docker images to verify that the container images are available with your chosen tag:

docker images | grep ghcr.io/usnistgov/dioptra

You should see output similar to the following (assuming the 1.0.0 tag):

REPOSITORY                                   TAG       IMAGE ID       CREATED         SIZE
ghcr.io/usnistgov/dioptra/nginx              1.0.0     17235f76d81c   3 weeks ago     243MB
ghcr.io/usnistgov/dioptra/restapi            1.0.0     f7e59af397ae   3 weeks ago     1.16GB
ghcr.io/usnistgov/dioptra/mlflow-tracking    1.0.0     56c574822dad   3 weeks ago     1.04GB
ghcr.io/usnistgov/dioptra/pytorch-cpu        1.0.0     5309d66defd5   3 weeks ago     3.74GB
ghcr.io/usnistgov/dioptra/tensorflow2-cpu    1.0.0     13c4784dd4f0   3 weeks ago     3.73GB

Note

The IMAGE ID, CREATED, and SIZE fields will vary. Verify that the REPOSITORY and TAG columns match your expected images.

Verifying Image Authenticity (Recommended)

Dioptra container images are cryptographically signed. Verifying these signatures confirms that the images you downloaded are authentic and have not been tampered with.

Step 4: Clone the Repository (If Not Already Done)

The public key needed for verification is stored in the Dioptra repository. Clone the repository if you have not already done so:

Clone with HTTPS

git clone https://github.com/usnistgov/dioptra.git

Clone with SSH

git clone [email protected]:usnistgov/dioptra.git

Step 5: Locate the Public Key

The repository root contains a verify.json file that specifies the path to the public key. Retrieve the key path:

cd dioptra
KEY_PATH=$(jq -r '.key_path' verify.json)

If you do not have jq installed, open verify.json and note the value of the key_path field (e.g., keys/dioptra.pub).

Step 6: Verify Each Image

Use cosign verify to verify each downloaded image. Run this command for each image, replacing the image name and tag as needed:

cosign verify --key "$KEY_PATH" ghcr.io/usnistgov/dioptra/nginx:$TAG

Successful verification produces output similar to:

Verification for ghcr.io/usnistgov/dioptra/nginx:1.0.0 --
The following checks were performed on each of these signatures:
    - The cosign claims were validated
    - Existence of the claims in the transparency log was verified offline
    - The signatures were verified against the specified public key

[{"critical":{"identity":{"docker-reference":"ghcr.io/usnistgov/dioptra/nginx"},"image":{"docker-manifest-digest":"sha256:531d71113540f892bc896bb99dcb7d250abd0b38de122600aa4409463c94b9e7"},"type":"cosign container image signature"},"optional":null}]

Repeat this step for each image you downloaded.

Tip

To verify all CPU images at once, you can use a loop:

for IMAGE in nginx restapi mlflow-tracking pytorch-cpu tensorflow2-cpu; do
  cosign verify --key "$KEY_PATH" "ghcr.io/usnistgov/dioptra/$IMAGE:$TAG"
done

If you also downloaded GPU images, add them to the loop:

for IMAGE in nginx restapi mlflow-tracking pytorch-cpu tensorflow2-cpu pytorch-gpu tensorflow2-gpu; do
  cosign verify --key "$KEY_PATH" "ghcr.io/usnistgov/dioptra/$IMAGE:$TAG"
done

Warning

If verification fails, do not use the image. Re-download the image and try again. If verification continues to fail, report the issue at usnistgov/dioptra#issues.

Warning

Downloaded images have a different registry prefix than locally built images. See Understanding Container Registry Prefixes for implications when configuring your deployment.

Next Steps

Once you have finished downloading the container images, move onto the next step: Prepare Your Deployment

See Also

• Prepare Your Deployment - Configure and start your Dioptra deployment

• Build the Container Images - Build images locally for customization

• Understanding Container Registry Prefixes - Understanding registry prefixes