High Priority: Implement version-aware container tagging

[tbrandenburg]

Problem

Docker configuration builds untagged images for local development only, creating high-risk deployment scenarios:

• Impossible to deploy specific versions in production
• latest tag provides no rollback capability
• Container images cannot be traced to source commits
• Production deployments become unreproducible

Evidence

• docker-compose.yml builds from local Dockerfiles without tags
• No container registry publishing
• Images tagged only as latest implicitly
• No OCI labels for traceability

Impact

High - Production container deployments are unreliable and non-traceable.

Recommended Solution

1. Tag images with version and commit SHA (e.g., v1.0.0, v1.0.0-abc1234)
2. Add OCI labels (version, commit, build date, source URL)
3. Publish to container registry (GitHub Container Registry)
4. Maintain both latest and version-specific tags

Acceptance Criteria

• Update Dockerfiles to accept version build args
• Add OCI labels to all container images
• Configure version-based image tagging in CI/CD
• Set up GitHub Container Registry publishing
• Update docker-compose.yml for version-aware deployments
• Document container versioning strategy

Priority

High - Required for production container deployments

[github-actions]

Investigation: High Priority: Implement version-aware container tagging

Issue: #302 (#302)
Type: ENHANCEMENT
Investigated: 2026-03-15T00:00:00Z

Assessment

Metric	Value	Reasoning
Priority	HIGH	Required for production deployments; blocking production reliability
Complexity	MEDIUM	2 Dockerfiles to modify, CI workflow updates, compose file changes
Confidence	HIGH	Clear requirements, well-understood Docker/OCI standards

---

Problem Statement

The current Docker configuration builds untagged images for local development only, creating high-risk deployment scenarios:

• Impossible to deploy specific versions in production
• latest tag provides no rollback capability
• Container images cannot be traced to source commits
• Production deployments become unreproducible

---

Analysis

Change Rationale

This enhancement adds version-aware container tagging to enable:

1. Version-specific deployments - Deploy exact versions (e.g., v1.0.0)
2. Rollback capability - Revert to previous versions via commit SHA tags
3. Traceability - OCI labels linking images to source commits
4. CI/CD integration - Automated publishing to container registry

Evidence Chain

CURRENT STATE: Images built without tags

• docker-compose.yml:6-8 - pybackend builds from docker/pybackend.Dockerfile with no tag
• docker-compose.yml:17-19 - frontend builds from docker/frontend.Dockerfile with no tag

REQUIRED CHANGES:

1. Add ARG/ENV for version in Dockerfiles
2. Add OCI labels (org.opencontainers.image.*)
3. Update docker-compose.yml to accept version args
4. Update CI workflow to tag and publish images

Affected Files

File	Lines	Action	Description
docker/pybackend.Dockerfile	1-26	UPDATE	Add version ARG and OCI labels
docker/frontend.Dockerfile	1-23	UPDATE	Add version ARG and OCI labels
docker-compose.yml	1-26	UPDATE	Add build args for version
.github/workflows/docker.yml	1-68	UPDATE	Add tagging and registry publishing
packages/pybackend/pyproject.toml	1-39	READ	Source of Python backend version
package.json	1-24	READ	Source of frontend version

Integration Points

• Makefile: make docker-build calls docker compose build - will pass version args
• CI/CD: GitHub Actions workflow needs to extract versions and tag images
• Version sources: package.json (version), packages/pybackend/pyproject.toml (version)

Git History

• Last modified: Commit d52f551 - Merge PR Show workflow stderr in Tasks diagnostics #298
• Dockerfiles added: Initial implementation (not recent)
• Implication: This is a new enhancement, not a regression

---

Implementation Plan

Step 1: Update pybackend Dockerfile with version ARG and OCI labels

File: docker/pybackend.Dockerfile
Lines: 1-26
Action: UPDATE

Current code:

# syntax=docker/dockerfile:1
FROM python:3.12-slim

WORKDIR /app

Required change:

# syntax=docker/dockerfile:1
ARG VERSION=dev
ARG COMMIT_SHA=unknown

FROM python:3.12-slim

WORKDIR /app

LABEL org.opencontainers.image.title="MADE Python Backend" \
      org.opencontainers.image.description="FastAPI backend for MADE" \
      org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.revision="${COMMIT_SHA}" \
      org.opencontainers.image.source="https://github.com/tbrandenburg/made" \
      org.opencontainers.image.created="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"

Why: Enable version traceability through OCI labels

---

Step 2: Update frontend Dockerfile with version ARG and OCI labels

File: docker/frontend.Dockerfile
Lines: 1-23
Action: UPDATE

Current code:

# syntax=docker/dockerfile:1
FROM node:18-alpine AS build

Required change:

# syntax=docker/dockerfile:1
ARG VERSION=dev
ARG COMMIT_SHA=unknown

FROM node:18-alpine AS build

LABEL org.opencontainers.image.title="MADE Frontend" \
      org.opencontainers.image.description="React frontend for MADE" \
      org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.revision="${COMMIT_SHA}" \
      org.opencontainers.image.source="https://github.com/tbrandenburg/made" \
      org.opencontainers.image.created="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"

Why: Enable version traceability through OCI labels

---

Step 3: Update docker-compose.yml with build args

File: docker-compose.yml
Lines: 1-26
Action: UPDATE

Current code:

services:
  pybackend:
    build:
      context: .
      dockerfile: docker/pybackend.Dockerfile

Required change:

services:
  pybackend:
    build:
      context: .
      dockerfile: docker/pybackend.Dockerfile
      args:
        VERSION: ${VERSION:-dev}
        COMMIT_SHA: ${COMMIT_SHA:-unknown}

And similarly for frontend:

  frontend:
    build:
      context: .
      dockerfile: docker/frontend.Dockerfile
      args:
        VERSION: ${VERSION:-dev}
        COMMIT_SHA: ${COMMIT_SHA:-unknown}

Why: Allow passing version and commit SHA at build time

---

Step 4: Update Docker CI workflow for tagging and publishing

File: .github/workflows/docker.yml
Lines: 1-68
Action: UPDATE

Add after "Set up Docker Buildx" step:

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=sha,prefix=
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Login to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push with version tags
        uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            VERSION=${{ github.ref_name }}-${{ github.sha }}
            COMMIT_SHA=${{ github.sha }}

Why: Automatically tag images with version and commit SHA, publish to GHCR

---

Step 5: Update Makefile docker-build target

File: Makefile
Lines: 220-222
Action: UPDATE (optional enhancement)

Add version-aware build:

docker-build:
	@echo "🐳 Building Docker images..."
	VERSION=$(shell node -p "require('./package.json').version") COMMIT_SHA=$(shell git rev-parse --short HEAD) docker compose build

Why: Enable version-aware local builds

---

Patterns to Follow

From existing Dockerfiles - mirror these exactly:

# SOURCE: docker/pybackend.Dockerfile:1
# Pattern for syntax directive
# syntax=docker/dockerfile:1

# SOURCE: docker-compose.yml:6-8
# Pattern for build configuration
build:
  context: .
  dockerfile: docker/pybackend.Dockerfile

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
No git available	Use "unknown" as default for COMMIT_SHA
No version in package.json	Fallback to "dev" if version not found
GHCR not enabled	Workflow still builds; push only on main branch
PR builds	Build without push; use tags for identification only

---

Validation

Automated Checks

# Build with version args
VERSION=v1.0.0 COMMIT_SHA=abc1234 docker compose build

# Verify labels in image
docker inspect --format='{{json .Config.Labels}}' made-pybackend | jq

# Expected labels:
# - org.opencontainers.image.version: v1.0.0
# - org.opencontainers.image.revision: abc1234

Manual Verification

1. Run make docker-build with VERSION and COMMIT_SHA set
2. Inspect built images with docker inspect to verify OCI labels
3. Verify CI workflow runs and tags appear on GHCR

---

Scope Boundaries

IN SCOPE:

• Add version ARG to Dockerfiles
• Add OCI labels to Dockerfiles
• Update docker-compose.yml for build args
• Update GitHub Actions workflow for tagging

OUT OF SCOPE (do not touch):

• Container registry beyond GitHub Container Registry (GHCR)
• Multi-arch builds (keep as-is)
• Existing tests (not affected by this change)

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-15T00:00:00Z
• Artifact: .ghar/issues/issue-302.md

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.