<< All versions
Skill v1.0.1
currentAutomated scan98/100majiayu000/claude-skill-registry/docker-registry-management
3 files
──Details
PublishedMay 17, 2026 at 01:43 PM
Content Hashsha256:62561112f6d84a6e...
Git SHAca303007d4fa
Bump Typepatch
──Files
Files (1 file, 14.2 KB)
SKILL.md14.2 KBactive
SKILL.md · 538 lines · 14.2 KB
version: "1.0.1"
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-amd64docker.io/battlescope/enrichment-service:v3.0.0-arm64docker.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:
amd64orarm64(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 releasev3.0.1 - Bug fix in ingestion servicev3.1.0 - Added historical ingestion featurev3.2.0 - Added data retention policy
Image Tags
Required Tags for Each Image:
- Specific Version:
v3.0.0-amd64 - Major.Minor:
v3.0-amd64 - Major:
v3-amd64 - Latest:
latest-amd64(ONLY for latest stable release)
Multi-Arch Manifest Tags:
- Specific Version:
v3.0.0(manifest pointing to all archs) - Major.Minor:
v3.0 - Major:
v3 - Latest:
latest
Example Push Sequence:
bash
# Build for amd64docker 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-amd64docker tag battlescope/ingestion-service:v3.0.0-amd64 battlescope/ingestion-service:v3-amd64docker tag battlescope/ingestion-service:v3.0.0-amd64 battlescope/ingestion-service:latest-amd64# Build for arm64docker 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-arm64docker tag battlescope/ingestion-service:v3.0.0-arm64 battlescope/ingestion-service:v3-arm64docker tag battlescope/ingestion-service:v3.0.0-arm64 battlescope/ingestion-service:latest-arm64# Push all tagsdocker push battlescope/ingestion-service:v3.0.0-amd64docker push battlescope/ingestion-service:v3.0-amd64docker push battlescope/ingestion-service:v3-amd64docker push battlescope/ingestion-service:latest-amd64docker push battlescope/ingestion-service:v3.0.0-arm64docker push battlescope/ingestion-service:v3.0-arm64docker push battlescope/ingestion-service:v3-arm64docker push battlescope/ingestion-service:latest-arm64# Create and push multi-arch manifestdocker manifest create battlescope/ingestion-service:v3.0.0 \battlescope/ingestion-service:v3.0.0-amd64 \battlescope/ingestion-service:v3.0.0-arm64docker manifest push battlescope/ingestion-service:v3.0.0docker manifest create battlescope/ingestion-service:v3.0 \battlescope/ingestion-service:v3.0-amd64 \battlescope/ingestion-service:v3.0-arm64docker manifest push battlescope/ingestion-service:v3.0docker manifest create battlescope/ingestion-service:v3 \battlescope/ingestion-service:v3-amd64 \battlescope/ingestion-service:v3-arm64docker manifest push battlescope/ingestion-service:v3docker manifest create battlescope/ingestion-service:latest \battlescope/ingestion-service:latest-amd64 \battlescope/ingestion-service:latest-arm64docker manifest push battlescope/ingestion-service:latest
3. BattleScope V3 Services
Service Image Names
| Service | Image Name | Description | |
|---|---|---|---|
| Ingestion | battlescope/ingestion-service | Raw killmail acquisition | |
| Enrichment | battlescope/enrichment-service | Killmail augmentation | |
| Battle | battlescope/battle-service | Battle clustering | |
| Search | battlescope/search-service | Full-text search | |
| Notification | battlescope/notification-service | Real-time notifications | |
| Frontend BFF | battlescope/frontend-bff | Backend-for-Frontend | |
| Frontend | battlescope/frontend | Web UI |
Infrastructure Images (if custom)
| Component | Image Name | Description | |
|---|---|---|---|
| Database Migrator | battlescope/db-migrator | Database migrations | |
| Init Container | battlescope/init | Initialization tasks |
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:
bash
# ❌ WRONG - Overwriting existing tagdocker build -t battlescope/ingestion-service:v3.0.0 .docker push battlescope/ingestion-service:v3.0.0 # Overwrites existing v3.0.0!# ✅ CORRECT - Create new versiondocker build -t battlescope/ingestion-service:v3.0.1 .docker push battlescope/ingestion-service:v3.0.1 # New tag, doesn't overwrite
Exception: latest tag can be updated (but use with caution in production)
5. Image Documentation
Docker Hub Repository Settings
For Each Service Repository:
- Description (Short):
`` BattleScope V3 - <Service Name> - <One-line description> ``
- Full Description (README.md):
```markdown # 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 manifestv3.0.0-amd64,v3.0-amd64,v3-amd64,latest-amd64- AMD64/x86_64v3.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
``bash curl http://localhost:<port>/health ``
## Documentation
## License
MIT ```
- Enable Auto-Build: If using GitHub integration
- Visibility: Public (for all BattleScope images)
6. Build Scripts
Makefile Integration
makefile
# Docker build variablesDOCKER_REGISTRY ?= docker.ioDOCKER_ORG ?= battlescopeVERSION ?= v3.0.0PLATFORMS ?= linux/amd64,linux/arm64# Service-specific variablesSERVICE_NAME := ingestion-serviceIMAGE_NAME := $(DOCKER_REGISTRY)/$(DOCKER_ORG)/$(SERVICE_NAME)# Build commands.PHONY: docker-build docker-push docker-build-push docker-manifest## Build Docker image for current platformdocker-build:@echo "Building $(IMAGE_NAME):$(VERSION) for current platform..."docker build -t $(IMAGE_NAME):$(VERSION) .## Build multi-arch Docker imagesdocker-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 imagedocker-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 pushdocker-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
yaml
# .github/workflows/docker-build.ymlname: Build and Push Docker Imageson:push:branches:- maintags:- 'v*.*.*'jobs:build-and-push:runs-on: ubuntu-lateststrategy:matrix:service:- ingestion-service- enrichment-service- battle-service- search-service- notification-service- frontend-bff- frontendsteps:- name: Checkout codeuses: actions/checkout@v4- name: Set up QEMUuses: docker/setup-qemu-action@v3- name: Set up Docker Buildxuses: docker/setup-buildx-action@v3- name: Login to Docker Hubuses: docker/login-action@v3with:username: ${{ secrets.DOCKER_USERNAME }}password: ${{ secrets.DOCKER_PASSWORD }}- name: Extract version from tagid: versionrun: |if [[ "${{ github.ref }}" =~ ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$ ]]; thenecho "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUTelseecho "VERSION=v3.0.0-dev-$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUTfi- name: Build and pushuses: docker/build-push-action@v5with:context: ./services/${{ matrix.service }}platforms: linux/amd64,linux/arm64push: truetags: |battlescope/${{ matrix.service }}:${{ steps.version.outputs.VERSION }}battlescope/${{ matrix.service }}:latestcache-from: type=registry,ref=battlescope/${{ matrix.service }}:buildcachecache-to: type=registry,ref=battlescope/${{ matrix.service }}:buildcache,mode=max
8. Image Security and Scanning
Best Practices
- Base Images:
``dockerfile # Use official Node.js LTS with Alpine for smaller size FROM node:20-alpine AS base ``
- Non-Root User:
``dockerfile # Create non-root user RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001 USER nodejs ``
- Multi-Stage Builds:
```dockerfile FROM node:20-alpine AS builder # Build stage
FROM node:20-alpine AS runner # Runtime stage (smaller final image) ```
- Security Scanning:
``bash # 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
latesttag
Delete:
- Dev/test tags older than 30 days
- Untagged images (dangling)
- Superseded patch versions (keep last 5 only)
Cleanup Script
bash
#!/bin/bash# cleanup-old-images.shREGISTRY="docker.io"ORG="battlescope"SERVICE="$1"# List all tagsTAGS=$(curl -s "https://hub.docker.com/v2/repositories/${ORG}/${SERVICE}/tags/?page_size=100" | jq -r '.results[].name')# Delete dev tags older than 30 daysfor TAG in $TAGS; doif [[ "$TAG" =~ -dev- ]]; then# Check age and delete if > 30 daysecho "Considering $TAG for deletion..."fidone
10. Kubernetes Image References
Pod Spec Image Reference
yaml
apiVersion: apps/v1kind: Deploymentmetadata:name: ingestion-servicespec:template:spec:containers:- name: ingestion-service# ✅ CORRECT - Use specific version tagimage: battlescope/ingestion-service:v3.0.0imagePullPolicy: 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 forlatesttag only, not recommended for production)Never- Never pull (use for local development only)
11. Image Registry Credentials
Docker Hub Authentication
Local Development:
bash
docker login docker.io# Enter username and password
Kubernetes Secret:
bash
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:
yaml
spec:imagePullSecrets:- name: docker-hub-creds
12. Troubleshooting
Common Issues
Issue: Image not found
bash
Error: Failed to pull image "battlescope/ingestion-service:v3.0.0": rpc error: code = NotFound
Solution:
bash
# Verify image existsdocker pull battlescope/ingestion-service:v3.0.0# Check tag exists on Docker Hubcurl https://hub.docker.com/v2/repositories/battlescope/ingestion-service/tags | jq '.results[].name'
Issue: Architecture mismatch
bash
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)
Solution:
bash
# 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!