docker

When to Use

• Writing or reviewing a Dockerfile
• Setting up compose for dev/test/prod
• Optimizing image size or build time
• Container security, networking, or volume management
• Containerizing a Spring Boot application

Engine agnosticism

Everything in this skill is spec OCI: the Dockerfile, the multi-stage build, the Compose spec files, and the feature flags shown run unchanged on Docker or Podman. The examples use docker CLI; substitute podman or lean on the podman-docker shim where it exists.

• Dockerfile semantics: Docker (BuildKit) ≈ Podman (Buildah). No docker-only Dockerfile instructions are used here.
• Compose: prefer the Compose spec files (compose.yaml) and a Compose v2 client. docker compose (v2.22+) works against a Podman socket via DOCKER_HOST; podman-compose implements less of the spec (notably no watch).
• Image scanning: trivy is the engine-neutral default (next section).
• Image versions in the examples below are illustrative (e.g. postgres:16-alpine); the production version is a project decision recorded in the project docs, not a rule of this skill.

Instructions

1. Multi-stage Builds for Spring Boot

# Stage 1: Build with Maven
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline -B
COPY src src
RUN mvn package -DskipTests -B

# Stage 2: Extract layered JAR for cache efficiency
RUN java -Djarmode=layertools -jar target/app.jar extract --destination extracted

# Stage 3: Runtime
FROM eclipse-temurin:21-jre-alpine
RUN addgroup -S app && adduser -S app -G app
USER app
WORKDIR /app
COPY --from=builder /app/extracted/dependencies/ ./
COPY --from=builder /app/extracted/spring-boot-loader/ ./
COPY --from=builder /app/extracted/snapshot-dependencies/ ./
COPY --from=builder /app/extracted/application/ ./
EXPOSE 8080
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

Use layered JARs so dependency layers cache independently from application code.

2. Dockerfile Best Practices

3. docker-compose Patterns

Dev environment with services:

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      SPRING_PROFILES_ACTIVE: dev
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/mydb
      SPRING_DATASOURCE_USERNAME: app
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    volumes:
      - ./target:/app/target  # hot reload in dev

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d mydb"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

4. Decision Table

5. Security

• Never hardcode secrets in Dockerfile or compose — use secrets mounts or env files
• USER nonroot — always
• COPY --chown=nonroot:nonroot — match the runtime user
• Read-only root filesystem: --read-only --tmpfs /tmp
• Scan with trivy (engine-neutral), e.g. trivy image myapp:latest; docker scout is Docker-only
• No curl/wget in runtime image — reduces attack surface

Commands

# Build (/docker | /podman — same OCI inputs through either engine)
docker build --cache-from myapp:latest -t myapp:latest .
podman build -t myapp:latest .

# Run with compose for dev (Compose spec client; engine-agnostic via socket)
docker compose up -d
DOCKER_HOST=unix:///run/user/1000/podman/podman.sock docker compose up -d

# Watch for hot reload (Compose v2.22+)
docker compose watch

# Scan image for vulnerabilities (engine-neutral)
trivy image myapp:latest
# Docker-only alternative: docker scout quick myapp:latest

# Run with read-only root fs (identical flag on docker and podman)
podman run --read-only --tmpfs /tmp myapp:latest

Resources

• Dockerfile reference
• Open Container Initiative spec
• Podman documentation
• Spring Boot layered JARs