docker-shared

Files (5)

• SKILL.md
• dockerignore-and-build-secrets.md · references/
• repo-evidence.md · references/
• shared-base-images.md · references/
• shared-compose-fragments.md · references/

SKILL.md (first lines)

# Shared Docker Building Blocks

Patterns for reusable Docker infrastructure across multiple services — base images, build hygiene, and compose fragment reuse.

## When to use

- Creating a base image to share heavy system dependencies (gcc, build-essential, postgres client, Kafka libs) across multiple related services
- Publishing base images to a private registry (Harbor, ECR, ACR, GCR) and consuming them with tag or digest pinning
- Handling private registry / package authentication during image builds
- Standardizing .dockerignore across services to exclude secrets, tests, and development artifacts
- Sharing compose configuration fragments (common env vars, resource limits, logging config) across services using YAML anchors and extension fields
- Connecting services to external infrastructure (shared Kafka cluster, Redis instance, custom network) via external networks and volumes

## Core conventions

### Shared Base Images

**Pattern**: Create a `Dockerfile.base` that installs heavy, rarely-changing system dependencies (build tools, database clients, language runtimes, system libraries). Publish it to a private registry with versioned tags. Service Dockerfiles then `FROM <registry>/<org>/<service>-base:<tag>` to inherit those layers.

**Why**: Avoids reinstalling the same heavy dependencies in every service Dockerfile; speeds up builds; ensures consistent system-level configuration across services.

**Tag vs digest pinning**: Use tags (`v1`, `v2`, `v12`) for active development; switch to digest pinning (`@sha256:...`) in production for immutable guarantees.

**Multi-service reuse**: A single base image can serve multiple related services that share dependencies (e.g., a Python 3.11 base with PostgreSQL client, Kafka libs, and Kerberos tools used by 3-4 backend services).

**Workflow**: Build the base image, push to registry with a new tag (e.g., `v13`), update service Dockerfiles to reference the new tag, rebuild service images.

### Private Registry Authentication

**Build-time auth with ARG**: Pass a private registry or package manager token as a `--build-arg` at build time. The Dockerfile declares `ARG REGISTRY_TOKEN` and uses it to authenticate `docker login`, `pip install` from private package indexes, or `curl` to fetch private scripts.

**CRITICAL ANTI-PATTERN**: **NEVER echo, print, or write a build-arg secret to a RUN layer or the console.** Even a debug `RUN echo "$REGISTRY_TOKEN"` or `printf "%s\n" "$REGISTRY_TOKEN"` bakes the secret into the image layer and build logs, making it recoverable from the final image or CI logs.

**Secure alternative**: Use BuildKit `--secret` and `RUN --mount=type=secret,id=token` for build-time secrets that never appear in layers. For local dev without BuildKit, use a `.env` file with the token and pass via `docker build --build-arg REGISTRY_TOKEN=$(cat .env | grep TOKEN | cut -d= -f2)`, but never commit the `.env`.

**Example ARG pattern** (genericized, with anti-pattern shown for educational purposes):

```dockerfile
# Dockerfile.base
FROM python:3.11-slim

ARG PRIVATE_REGISTRY_TOKEN

# ❌ ANTI-PATTERN: This bakes the token into the image layer and build logs
# RUN echo "===== TOKEN START =====" && \
#     printf "%s\n" "$PRIVATE_REGISTRY_TOKEN" && \
#     echo "===== TOKEN END ====="

# ✅ Correct: Use the token WITHOUT printing it
RUN apt-get update && \
    apt-get install -y curl git && \
    curl -H "Authorization: Bearer $PRIVATE_REGISTRY_TOKEN" \
         https://internal-registry.example.com/scripts/setup.sh -o /tmp/setup.sh && \
    sh /tmp/setup.sh && \
    rm /tmp/setup.sh
```

**BuildKit secret mount** (preferred):

```dockerfile
# syntax=docker/dockerfile:1.4
FROM python:3.11-slim

RUN --mount=type=secret,id=registry_token \
    REGISTRY_TOKEN=$(cat /run/secrets/registry_token) && \
    curl -H "Authorization: Bearer $REGISTRY_TOKEN" \
         https://internal-registry.example.com/scripts/setup.sh -o /tmp/setup.sh && \
    sh /tmp/setup.sh && \
    rm /tmp/setup.sh

# Build with: docker buildx build --secret id=registry_token,src=token.txt .
```

### .dockerignore Conventions

**Purpose**: Exclude files from the build context to reduce image size, speed up builds, and prevent secrets from leaking into images.

**Standard exclusions**:
- **Version control**: `.git`, `.gitignore`
- **Dependencies**: `node_modules/`, `.venv/`, `venv/`, `__pycache__/`, `*.pyc`
- **Tests and coverage**: `tests/`, `*.test.js`, `.pytest_cache/`, `.coverage`, `htmlcov/`
- **Secrets**: `.env`, `.env.local`, `.env.*.local`, `.env.secrets`, `*.key`, `*.pem` (unless explicitly needed)
- **IDE**: `.vscode/`, `.idea/`, `*.swp`, `*.swo`
- **OS**: `.DS_Store`, `Thumbs.db`
- **Logs and artifacts**: `*.log`, `logs/`, `screenshots/`, `videos/`, `dist/`, `build/`
- **Docker files**: `Dockerfile*`, `docker-compose*`, `.dockerignore` (the Docker files themselves don't belong in the image)
- **Documentation**: `*.md`, `docs/` (unless your image serves docs)

**Include exceptions**: Use `!` to re-include specific files after a broader exclusion (e.g., `*.md` excludes all markdown, `!README.md` includes only the README).

**Example .dockerignore**:

```
# Version control
.git
.gitignore

# Dependencies
node_modules
npm-debug.log*
__pycache__
*.pyc
.venv
venv

# Tests
tests/
.pytest_cache/
.coverage
htmlcov/

# Secrets
.env
.env.*
*.key
*.pem

# IDE
.vscode

From ajyadav013/claude-kit, MIT.

More from ajyadav013/claude-kit