Claude Skill: Docker Registry Management for BattleScope

Purpose: Guide all Docker image building, tagging, versioning, and registry management for BattleScope services.

Core Principles

1. Image Naming Convention

Rule: All BattleScope images MUST follow this naming pattern:

<registry>/<organization>/<service>:<version>-<architecture>

Examples:

docker.io/battlescope/ingestion-service:v3.0.0-amd64
docker.io/battlescope/enrichment-service:v3.0.0-arm64
docker.io/battlescope/battle-service:v3.1.2-amd64

Components:

• Registry:

  docker.io

  (Docker Hub - public registry)
• Organization:

  battlescope

• Service: Service name in kebab-case
• Version: Semantic versioning (v3.x.x for V3 architecture)
• Architecture:

  amd64

  or

  arm64

  (multi-arch support)

2. Versioning Strategy

Semantic Versioning

Format:

vMAJOR.MINOR.PATCH

V3 Architecture:

• Major Version:

  v3

  (V3 architecture)
• Minor Version: Feature additions, non-breaking changes
• Patch Version: Bug fixes, minor updates

Examples:

v3.0.0 - Initial V3 release
v3.0.1 - Bug fix in ingestion service
v3.1.0 - Added historical ingestion feature
v3.2.0 - Added data retention policy

Image Tags

Required Tags for Each Image:

1. Specific Version:

   v3.0.0-amd64

2. Major.Minor:

   v3.0-amd64

3. Major:

   v3-amd64

4. Latest:

   latest-amd64

   (ONLY for latest stable release)

Multi-Arch Manifest Tags:

1. Specific Version:

   v3.0.0

   (manifest pointing to all archs)
2. Major.Minor:

   v3.0

3. Major:

   v3

4. Latest:

   latest

Example Push Sequence:

# Build for amd64
docker build --platform linux/amd64 -t battlescope/ingestion-service:v3.0.0-amd64 .
docker tag battlescope/ingestion-service:v3.0.0-amd64 battlescope/ingestion-service:v3.0-amd64
docker tag battlescope/ingestion-service:v3.0.0-amd64 battlescope/ingestion-service:v3-amd64
docker tag battlescope/ingestion-service:v3.0.0-amd64 battlescope/ingestion-service:latest-amd64

# Build for arm64
docker build --platform linux/arm64 -t battlescope/ingestion-service:v3.0.0-arm64 .
docker tag battlescope/ingestion-service:v3.0.0-arm64 battlescope/ingestion-service:v3.0-arm64
docker tag battlescope/ingestion-service:v3.0.0-arm64 battlescope/ingestion-service:v3-arm64
docker tag battlescope/ingestion-service:v3.0.0-arm64 battlescope/ingestion-service:latest-arm64

# Push all tags
docker push battlescope/ingestion-service:v3.0.0-amd64
docker push battlescope/ingestion-service:v3.0-amd64
docker push battlescope/ingestion-service:v3-amd64
docker push battlescope/ingestion-service:latest-amd64
docker push battlescope/ingestion-service:v3.0.0-arm64
docker push battlescope/ingestion-service:v3.0-arm64
docker push battlescope/ingestion-service:v3-arm64
docker push battlescope/ingestion-service:latest-arm64

# Create and push multi-arch manifest
docker manifest create battlescope/ingestion-service:v3.0.0 \
  battlescope/ingestion-service:v3.0.0-amd64 \
  battlescope/ingestion-service:v3.0.0-arm64
docker manifest push battlescope/ingestion-service:v3.0.0

docker manifest create battlescope/ingestion-service:v3.0 \
  battlescope/ingestion-service:v3.0-amd64 \
  battlescope/ingestion-service:v3.0-arm64
docker manifest push battlescope/ingestion-service:v3.0

docker manifest create battlescope/ingestion-service:v3 \
  battlescope/ingestion-service:v3-amd64 \
  battlescope/ingestion-service:v3-arm64
docker manifest push battlescope/ingestion-service:v3

docker manifest create battlescope/ingestion-service:latest \
  battlescope/ingestion-service:latest-amd64 \
  battlescope/ingestion-service:latest-arm64
docker manifest push battlescope/ingestion-service:latest

3. BattleScope V3 Services

Service Image Names

battlescope/ingestion-service

battlescope/enrichment-service

battlescope/battle-service

battlescope/search-service

battlescope/notification-service

battlescope/frontend-bff

battlescope/frontend

Infrastructure Images (if custom)

battlescope/db-migrator

battlescope/init

4. Never Overwrite Production Tags

CRITICAL RULE: NEVER overwrite existing production image tags.

Why:

• Running pods may pull "updated" image causing inconsistency
• Rollbacks become impossible
• Audit trail is lost
• Violates immutability principle

Correct Approach:

# ❌ WRONG - Overwriting existing tag
docker build -t battlescope/ingestion-service:v3.0.0 .
docker push battlescope/ingestion-service:v3.0.0  # Overwrites existing v3.0.0!

# ✅ CORRECT - Create new version
docker build -t battlescope/ingestion-service:v3.0.1 .
docker push battlescope/ingestion-service:v3.0.1  # New tag, doesn't overwrite

Exception:

latest

5. Image Documentation

Docker Hub Repository Settings

For Each Service Repository:

1. Description (Short):

   BattleScope V3 - <Service Name> - <One-line description>
   

2. Full Description (README.md):

   # BattleScope <Service Name>
   
   **Architecture**: V3 Distributed Microservices
   **Version**: v3.x.x
   
   ## Overview
   
   <Service description from service specification>
   
   ## Supported Tags
   
   - `v3.0.0`, `v3.0`, `v3`, `latest` - Multi-arch manifest
   - `v3.0.0-amd64`, `v3.0-amd64`, `v3-amd64`, `latest-amd64` - AMD64/x86_64
   - `v3.0.0-arm64`, `v3.0-arm64`, `v3-arm64`, `latest-arm64` - ARM64
   
   ## Quick Start
   
   ```bash
   docker pull battlescope/<service-name>:v3
   docker run -p <port>:<port> battlescope/<service-name>:v3
   

   Environment Variables

   Variable	Description	Default
   PORT	Service port	3000
   KAFKA_BROKERS	Kafka connection string	localhost:9092
   DATABASE_URL	PostgreSQL connection string	Required

   Health Check

   curl http://localhost:<port>/health
   

   Documentation

   • Architecture
   • Service Specification

   License

   MIT

3. Enable Auto-Build: If using GitHub integration

4. Visibility: Public (for all BattleScope images)

6. Build Scripts

Makefile Integration

# Docker build variables
DOCKER_REGISTRY ?= docker.io
DOCKER_ORG ?= battlescope
VERSION ?= v3.0.0
PLATFORMS ?= linux/amd64,linux/arm64

# Service-specific variables
SERVICE_NAME := ingestion-service
IMAGE_NAME := $(DOCKER_REGISTRY)/$(DOCKER_ORG)/$(SERVICE_NAME)

# Build commands
.PHONY: docker-build docker-push docker-build-push docker-manifest

## Build Docker image for current platform
docker-build:
	@echo "Building $(IMAGE_NAME):$(VERSION) for current platform..."
	docker build -t $(IMAGE_NAME):$(VERSION) .

## Build multi-arch Docker images
docker-build-multi:
	@echo "Building $(IMAGE_NAME):$(VERSION) for $(PLATFORMS)..."
	docker buildx build \
		--platform $(PLATFORMS) \
		-t $(IMAGE_NAME):$(VERSION) \
		-t $(IMAGE_NAME):$(shell echo $(VERSION) | cut -d. -f1-2) \
		-t $(IMAGE_NAME):$(shell echo $(VERSION) | cut -d. -f1) \
		-t $(IMAGE_NAME):latest \
		.

## Push Docker image
docker-push:
	@echo "Pushing $(IMAGE_NAME):$(VERSION)..."
	docker push $(IMAGE_NAME):$(VERSION)
	docker push $(IMAGE_NAME):$(shell echo $(VERSION) | cut -d. -f1-2)
	docker push $(IMAGE_NAME):$(shell echo $(VERSION) | cut -d. -f1)
	docker push $(IMAGE_NAME):latest

## Build and push (convenience command)
docker-build-push: docker-build docker-push

## Build multi-arch and push
docker-build-push-multi:
	@echo "Building and pushing $(IMAGE_NAME):$(VERSION) for $(PLATFORMS)..."
	docker buildx build \
		--platform $(PLATFORMS) \
		--push \
		-t $(IMAGE_NAME):$(VERSION) \
		-t $(IMAGE_NAME):$(shell echo $(VERSION) | cut -d. -f1-2) \
		-t $(IMAGE_NAME):$(shell echo $(VERSION) | cut -d. -f1) \
		-t $(IMAGE_NAME):latest \
		.

7. GitHub Actions CI/CD

Automated Image Building

# .github/workflows/docker-build.yml
name: Build and Push Docker Images

on:
  push:
    branches:
      - main
    tags:
      - 'v*.*.*'

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service:
          - ingestion-service
          - enrichment-service
          - battle-service
          - search-service
          - notification-service
          - frontend-bff
          - frontend

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Extract version from tag
        id: version
        run: |
          if [[ "${{ github.ref }}" =~ ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
          else
            echo "VERSION=v3.0.0-dev-$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
          fi

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: ./services/${{ matrix.service }}
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            battlescope/${{ matrix.service }}:${{ steps.version.outputs.VERSION }}
            battlescope/${{ matrix.service }}:latest
          cache-from: type=registry,ref=battlescope/${{ matrix.service }}:buildcache
          cache-to: type=registry,ref=battlescope/${{ matrix.service }}:buildcache,mode=max

8. Image Security and Scanning

Best Practices

1. Base Images:

   # Use official Node.js LTS with Alpine for smaller size
   FROM node:20-alpine AS base
   

2. Non-Root User:

   # Create non-root user
   RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
   USER nodejs
   

3. Multi-Stage Builds:

   FROM node:20-alpine AS builder
   # Build stage
   
   FROM node:20-alpine AS runner
   # Runtime stage (smaller final image)
   

4. Security Scanning:

   # Scan images before pushing
   docker scan battlescope/ingestion-service:v3.0.0
   

9. Registry Cleanup Policy

Retention Rules

Keep:

• All major versions (v3.x.x, v4.x.x, etc.)
• Last 10 minor versions of current major
• Last 5 patch versions of current minor

• latest

  tag

Delete:

• Dev/test tags older than 30 days
• Untagged images (dangling)
• Superseded patch versions (keep last 5 only)

Cleanup Script

#!/bin/bash
# cleanup-old-images.sh

REGISTRY="docker.io"
ORG="battlescope"
SERVICE="$1"

# List all tags
TAGS=$(curl -s "https://hub.docker.com/v2/repositories/${ORG}/${SERVICE}/tags/?page_size=100" | jq -r '.results[].name')

# Delete dev tags older than 30 days
for TAG in $TAGS; do
  if [[ "$TAG" =~ -dev- ]]; then
    # Check age and delete if > 30 days
    echo "Considering $TAG for deletion..."
  fi
done

10. Kubernetes Image References

Pod Spec Image Reference

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ingestion-service
spec:
  template:
    spec:
      containers:
        - name: ingestion-service
          # ✅ CORRECT - Use specific version tag
          image: battlescope/ingestion-service:v3.0.0
          imagePullPolicy: IfNotPresent

          # ❌ WRONG - Using 'latest' in production
          # image: battlescope/ingestion-service:latest
          # imagePullPolicy: Always

Image Pull Policy:

• IfNotPresent

  - Pull only if not cached (recommended for versioned tags)

• Always

  - Always pull (use for

  latest

  tag only, not recommended for production)

• Never

  - Never pull (use for local development only)

11. Image Registry Credentials

Docker Hub Authentication

Local Development:

docker login docker.io
# Enter username and password

Kubernetes Secret:

kubectl create secret docker-registry docker-hub-creds \
  --docker-server=docker.io \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email> \
  --namespace=battlescope

Pod Spec:

spec:
  imagePullSecrets:
    - name: docker-hub-creds

12. Troubleshooting

Common Issues

Issue: Image not found

Error: Failed to pull image "battlescope/ingestion-service:v3.0.0": rpc error: code = NotFound

Solution:

# Verify image exists
docker pull battlescope/ingestion-service:v3.0.0

# Check tag exists on Docker Hub
curl https://hub.docker.com/v2/repositories/battlescope/ingestion-service/tags | jq '.results[].name'

Issue: Architecture mismatch

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

Solution:

# Pull multi-arch manifest (not architecture-specific tag)
docker pull battlescope/ingestion-service:v3.0.0  # Multi-arch manifest
# NOT: battlescope/ingestion-service:v3.0.0-amd64

Summary Checklist

Before pushing any image:

• Image follows naming convention:

  battlescope/<service>:v3.x.x

• Version tag is unique (not overwriting existing tag)
• Multi-arch build (amd64 + arm64)
• All required tags created (version, major.minor, major, latest)
• Docker Hub repository has proper description
• Image scanned for vulnerabilities
• Kubernetes manifests updated with new version
• CHANGELOG updated with new version

Remember: Images are immutable. Never overwrite an existing production tag!