Skip to content
Spike Documentation

Build and publish images with Podman

Use Podman to create images that are reproducible, project-scoped, and easy to trace. Choose a CUDA base image that matches your workload requirements, install only the required dependencies, and run the application as a non-root user.

Choose a trusted base image

Section titled “Choose a trusted base image”

For GPU workloads, start with an image maintained by the software vendor. The NVIDIA NGC CUDA catalog publishes the nvcr.io/nvidia/cuda images used in the example below, including their tags, layers, licenses, and security-scan results. Framework-specific NGC images can also be a useful starting point when they match the approved Spike software stack.

Use these rules when selecting a base:

  • Ask your SCC AI Engineer which CUDA family is compatible with Spike before choosing a tag. A newer tag is not automatically compatible with the cluster.
  • Pin a complete versioned tag; never depend on latest. Record the resolved image digest with the project so the build can be reproduced.
  • Prefer a runtime image for the final workload. Use a devel image only while compiling, ideally as the build stage of a multi-stage Containerfile.
  • Review the image’s license, support status, and NGC security scan. Rebuild and rescan your project image when the base or an installed dependency receives a security update.
  • Do not use an unverified personal or community image merely because it already contains the packages you need. An official base still needs project-specific dependency review and secret handling.

A minimal Containerfile

Section titled “A minimal Containerfile”
FROM nvcr.io/nvidia/cuda:12.8.0-cudnn-runtime-ubuntu22.04
RUN useradd --create-home --uid 10001 researcher
WORKDIR /workspace
COPY requirements.txt .
RUN apt-get update && apt-get install -y --no-install-recommends python3-pip \\
  && pip3 install --no-cache-dir -r requirements.txt \\
  && rm -rf /var/lib/apt/lists/*
COPY --chown=researcher:researcher . .
USER researcher
CMD ["python3", "train.py"]

Do not place registry passwords, model tokens, or private keys in the image, the Containerfile, or source control. Provide them through the approved runtime secret mechanism instead.

Build and push

Section titled “Build and push”
  1. Sign in interactively: podman login harbor.spike.tue.nl.
  2. Open the canonical build-and-push script in a new tab and save it locally.
  3. Run bash push-to-harbor.sh CONTAINER_NAME HARBOR_PROJECT VERSION Containerfile.

The script validates its four arguments, builds linux/amd64, and publishes:

harbor.spike.tue.nl/HARBOR_PROJECT/CONTAINER_NAME:VERSION

Use immutable version tags such as 1.0.0 or a revision identifier. Do not overwrite a tag that another workload may need for reproducibility. Update a workload environment only after the new tag is visible in Harbor.

SSH-container example location

Section titled “SSH-container example location”

The approved SSH file-transfer example is published in this site under /downloads/ssh-container/. Start with the SSH-container Containerfile, then keep the matching SSH configuration, startup script, and README in the same build directory. Each example opens in a new tab. The File transfer guide explains how to build it, select a CPU-only workspace, mount /data, and use Run:ai port forwarding with scp.

Common failures

Section titled “Common failures”
  • Login is rejected: refresh access with podman login harbor.spike.tue.nl and confirm Harbor project membership.
  • Push is denied: check the exact Harbor project name and your write role.
  • Image pull fails in Run:ai: check the image path and tag, then ensure the workload project can access the Harbor project.