netresearch Docker Development
Core Principles
- Minimal -- Alpine/distroless, multi-stage
- Secure -- Non-root USER, no layer secrets, pin versions
- Testable -- entrypoint bypass, DNS mocking
- Cache-efficient -- deps first, clean in-layer
Quick Reference
Multi-Stage Build (Node.js)
FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
FROM node:24-alpine
RUN addgroup -g 1001 app && adduser -u 1001 -G app -D app
USER app
COPY --from=builder /app .
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "server.js"]
Multi-Stage Build (Go -- scratch/distroless)
FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server .
FROM gcr.io/distroless/static:nonroot
COPY --from=builder /app/server /server
CMD ["/server"]
Layer Optimization
RUN apt-get update && \
apt-get install -y --no-install-recommends curl && \
rm -rf /var/lib/apt/lists/*
Build Cache: Copy Dependency Files First
COPY package*.json ./
RUN npm ci
COPY . .
Manifests before source keeps install layers cached.
BuildKit Secrets
RUN --mount=type=secret,id=ssh_key,dst=/root/.ssh/id_rsa git clone git@github.com:org/repo.git
ARG leaks via docker history and SLSA provenance --
references/build-secret-leaks.md
Docker Bake (Multi-Platform)
target "app" {
platforms = ["linux/amd64", "linux/arm64"]
cache-from = ["type=gha"]
cache-to = ["type=gha,mode=max"]
}
Security Anti-Patterns
| Anti-pattern | Fix |
|---|---|
FROM image:latest |
Pin version: image:1.2.3-alpine |
No USER directive |
adduser + USER appuser |
chmod 777 |
Use specific permissions: chmod 550 |
privileged: true in compose |
Remove or use specific cap_add |
volumes: [/:/host] |
Mount only needed paths |
ports: ["0.0.0.0:3000:3000"] |
Bind to 127.0.0.1:3000:3000 |
ENV DB_PASSWORD=secret |
Use --mount=type=secret or compose secrets |
CI Testing Gotchas
- Bypass entrypoint:
docker run --rm --entrypoint php myimage -v - Mock upstream DNS:
docker run --rm --add-host backend:127.0.0.1 nginx-image nginx -t - Compose validation:
cp .env.example .envbeforedocker compose config - Secret scanning: exclude
.env.example, README, docs - Root-owned artifacts: bind-mount dirs (
EACCES) --references/bind-mount-ownership.md
.dockerignore
Exclude: .git, node_modules/vendor, .env*, *.pem, *.key
Compose Essentials
- startup ordering:
depends_on.condition: service_healthy+healthcheckstart_period networks.internal: trueisolates databasesprofiles: [debug]: start only with--profile debug- shared image ref: define ONCE per file as top-level extension field + anchor --
x-app-image: &app-image registry/app:${APP_IMAGE_VERSION:-85}, services useimage: *app-image. The field must sit ABOVEservices:— an alias is only valid after its anchor in document order.:-defaults cover unset AND empty vars (a bare omitted tag silently resolves:latest). Anchors are file-local: every overlay file needs its own. Verify both paths:APP_IMAGE_VERSION= docker compose configand with an override
References
references/ci-testing.md-- CI testing patterns for Docker imagesreferences/dind-testing-patterns.md-- Docker-in-Docker testing patternsreferences/bind-mount-ownership.md-- root-owned bind-mount artifactsreferences/gpg-verification.md-- gpgv patterns; stale keybox locksreferences/registry-catalogue-and-pin-rot.md-- catalogue probes; pin rotreferences/build-secret-leaks.md--ARGin provenancereferences/php-fpm-worker-starvation.md-- keepalive pins php-fpm