Golden Container (Optum Golden Images)

Use this skill when the user wants a Dockerfile that must follow Optum golden image standards. This is the master skill — it works for any technology in the golden image catalog (Node.js, Python, Go, Java, .NET, Ruby, Rust, Nginx, and 100+ others).

For technology-specific refinements see the companion skills:

• node-container — Node.js Dockerfile patterns
• python-container — Python Dockerfile patterns

Core Concepts

What Are Golden Images?

Optum golden images are hardened, pre-scanned base container images hosted in JFrog Artifactory. Every production container must descend from one of these images. They are rebuilt regularly with OS patches and published under a predictable tag scheme.

Registry Path

All golden images live under a single Artifactory virtual repository:

edgeinternal1uhg.optum.com:443/glb-docker-uhg-loc/uhg-goldenimages/<PRODUCT>:<TAG>

Tag Convention

Every product follows the same tag pattern:

Tag	Purpose	Example
<VERSION>-latest	Runtime — minimal, no compilers or dev tools	node:24-latest
<VERSION>-latest-dev	Build stage — includes compilers, headers, dev tools	python:3.14-latest-dev
<VERSION>-slim-latest	Slim runtime — even smaller footprint (not always available)	node:24-slim-latest
latest	Floating alias — tracks the newest supported major	go:latest
latest-dev	Floating alias (dev) — tracks the newest supported major dev variant	go:latest-dev

Best practice: pin to a versioned tag (<VERSION>-latest) rather than the unversioned latest alias so builds are reproducible.

Multi-Stage Build Pattern

All Dockerfiles follow a two-stage pattern:

┌──────────────────────────────┐
│  Stage 1: builder            │  <PRODUCT>:<VERSION>-latest-dev
│  - Install dependencies      │
│  - Compile / build           │
│  - Prune dev-only artifacts  │
└──────────┬───────────────────┘
           │ COPY artifacts
           ▼
┌──────────────────────────────┐
│  Stage 2: runtime            │  <PRODUCT>:<VERSION>-latest
│  - Copy built app            │
│  - Set WORKDIR, ENV, EXPOSE  │
│  - ENTRYPOINT / CMD          │
└──────────────────────────────┘

Key rules:

1. Never install compilers or dev headers in the runtime stage.
2. Never run as USER root — golden images ship with a non-root user.
3. Always set WORKDIR /app.
4. Use COPY --from=builder to bring only production artifacts forward.

Golden Image Navigator API

The API at https://golden-image-dashboard.optum.com is the authoritative source for discovering products, versions, and image metadata.

API Endpoints

Endpoint	Purpose
GET /api/products	List every product in the catalog
GET /api/products/<PRODUCT>	Get supported versions for a product
GET /api/images/<PRODUCT>:<TAG>	Get metadata for a specific image tag
GET /api/images?search=<TERM>	Search images by keyword (exploration only)

Response Shapes

Products list — GET /api/products:

{
  "api_info": { "api_path": "/api/products" },
  "data": {
    "products": [
      { "name": "node", "lifecycle": "major" /* ... */ },
      { "name": "python", "lifecycle": "major.minor" /* ... */ },
      // 100+ products
    ],
  },
}

Single product — GET /api/products/<PRODUCT>:

{
  "data": {
    "product": { "name": "go", "lifecycle": "major.minor" },
    "total_versions": 3,
    "versions": [
      {
        "version": "1.26",
        "is_supported": true,
        "eol_status": "supported",
        "image_count": 2,
      },
      {
        "version": "1.25",
        "is_supported": true,
        "eol_status": "supported",
        "image_count": 2,
      },
      {
        "version": "latest",
        "is_supported": true,
        "eol_status": "supported",
        "image_count": 2,
      },
    ],
  },
}

Image detail — GET /api/images/<PRODUCT>:<TAG>:

{
  "data": {
    "product_name": "go",
    "tag": "1.26-latest-dev",
    "version": "1.26",
    "is_supported": true,
    "image_status": "OK", // OK | UNKNOWN | DEPRECATED
    "build_date": "2026-05-15",
    "artifactory_path": "https://centraluhg.jfrog.io/ui/repos/tree/General/glb-docker-uhg-loc/uhg-goldenimages/go/1.26-latest-dev",
    "architectures": [
      { "platform": "linux/amd64" },
      { "platform": "linux/arm64" },
    ],
  },
}

Workflow — Any Technology

1. Identify the product name by listing the catalog or checking the product endpoint.
2. Discover the latest supported version for that product.
3. Verify image tags exist and are supported for both the runtime and dev variants.
4. Generate the Dockerfile using the multi-stage template.
5. Validate that the chosen tags are is_supported: true and image_status: "OK".

Step-by-step

# 1. Find the product
scripts/01-list-products.sh                    # → full catalog
scripts/02-get-product.sh <PRODUCT>            # → supported versions

# 2. Get the latest supported concrete version
#    Pick the highest version where is_supported == true and
#    version != "latest".

# 3. Verify image tags
scripts/03-get-image.sh <PRODUCT>:<VERSION>-latest
scripts/03-get-image.sh <PRODUCT>:<VERSION>-latest-dev

# 4. (Optional) Check slim variant availability
scripts/03-get-image.sh <PRODUCT>:<VERSION>-slim-latest

# 5. (Optional) Explore by keyword
scripts/04-search-images.sh <TERM>

Recommended Selection Flow (Generic)

1. Query /api/products/<PRODUCT>
2. Filter versions where is_supported == true
3. Exclude the synthetic "latest" entry
4. Sort remaining versions descending (semantic or numeric)
5. Pick the highest → that is your <VERSION>
6. Runtime base  → <PRODUCT>:<VERSION>-latest
7. Build base    → <PRODUCT>:<VERSION>-latest-dev
8. Slim (opt-in) → <PRODUCT>:<VERSION>-slim-latest (only if is_supported)

Scripts

The scripts/ directory contains four generic scripts that work with any product in the catalog. They all respect BASE_URL for overrides.

Script	Purpose	Usage
01-list-products.sh	List all product names	./scripts/01-list-products.sh
02-get-product.sh	Show versions for a product	./scripts/02-get-product.sh node
03-get-image.sh	Get image metadata for a tag	./scripts/03-get-image.sh python:3.14-latest-dev
04-search-images.sh	Search images by keyword	./scripts/04-search-images.sh nginx

Template

template/Dockerfile.template is a generic multi-stage Dockerfile with placeholder variables. Replace the placeholders before use:

Placeholder	Description	Example
{{PRODUCT}}	Golden image product name	node, python, go
{{VERSION}}	Pinned version from API discovery	24, 3.14, 1.26
{{COPY_MANIFESTS}}	Copy dependency manifests before installing dependencies	COPY package*.json ./, COPY requirements.txt .
{{INSTALL_DEPS}}	Command to install dependencies	npm ci, pip install --user -r requirements.txt
{{COPY_RUNTIME_DEPS}}	Copy installed runtime dependencies into the final image (if needed)	COPY --from=builder /home/nonroot/.local /home/nonroot/.local
{{BUILD_CMD}}	Optional compile/transpile step	npm run build, go build -o /app/server .
{{PRUNE_CMD}}	Optional dev-dependency removal	npm prune --omit=dev
{{ENV_VARS}}	Runtime environment variables	ENV NODE_ENV=production
{{PORT}}	Port the application listens on	3000, 8000, 8080
{{ENTRYPOINT}}	Application start command	["node", "server.js"]

Technology-Specific Patterns

Below are condensed recipes for common technologies. Each follows the same multi-stage pattern but differs in dependency installation and artifact copying.

Node.js

# Build
FROM .../node:24-latest-dev AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm prune --omit=dev

# Runtime
FROM .../node:24-latest
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app /app
EXPOSE 3000
ENTRYPOINT ["node", "server.js"]

Python

# Build
FROM .../python:3.14-latest-dev AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt
COPY . .

# Runtime
FROM .../python:3.14-latest
WORKDIR /app
COPY --from=builder /home/nonroot/.local /home/nonroot/.local
COPY --from=builder /app /app
ENV PATH=/home/nonroot/.local/bin:$PATH
EXPOSE 8000
ENTRYPOINT ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Go

# Build
FROM .../go:1.26-latest-dev AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server .

# Runtime — Go compiles to static binaries; use the smallest base
FROM .../static:latest
COPY --from=builder /app/server /app/server
ENTRYPOINT ["/app/server"]

Java (JDK/JRE)

# Build
FROM .../jdk:21-latest-dev AS builder
WORKDIR /app
COPY . .
RUN ./gradlew bootJar --no-daemon

# Runtime
FROM .../jre:21-latest
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

.NET

# Build
FROM .../dotnet-sdk:9.0-latest AS builder
WORKDIR /src
COPY *.csproj .
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish

# Runtime
FROM .../aspnet-runtime:9.0-latest
WORKDIR /app
COPY --from=builder /app/publish .
EXPOSE 8080
ENTRYPOINT ["dotnet", "MyApp.dll"]

Nginx (Static Sites)

# Build (e.g., React/Vue/Angular)
FROM .../node:24-latest-dev AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runtime
FROM .../nginx:latest
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

Validation Checklist

Before merging any Dockerfile that uses golden images:

• Runtime base uses <VERSION>-latest (not -dev).
• Build stage uses <VERSION>-latest-dev.
• Tags verified against API (is_supported: true, image_status: "OK").
• No USER root in the Dockerfile.
• WORKDIR /app set in both stages.
• Dev dependencies and build tools are NOT in the final image.
• EXPOSE matches the application's listen port.
• ENTRYPOINT or CMD starts the correct process.

References

• ../../instructions/docker.instructions.md
• ../../instructions/optum-golden-containers.instructions.md
• ../../skills/node-container/ — Node.js-specific skill
• ../../skills/python-container/ — Python-specific skill