docker

name	docker
description	Docker and Compose: image builds, container lifecycle, networking, volume management, and safety conventions for this repo.
user-invocable	false
allowed-tools	["Bash(docker *)","Bash(docker-compose *)","Bash(podman *)"]

Docker Domain Guide

This repo uses Docker. Apply these patterns.

Dockerfile Conventions

• Pin base image tags: FROM rust:1.78-slim-bookworm, not FROM rust:latest.
• Use multi-stage builds to keep final images small.
• COPY specific files/directories — never COPY . . in the final stage.
• Run as non-root: add USER nonroot after installing dependencies.
• Combine RUN commands with && to reduce layers; clean package caches in the same layer.

Image Builds

• Build with --no-cache in CI to catch cache-corruption bugs.
• Tag with both sha and semantic version: never push latest as the only tag to production.
• Scan images for vulnerabilities before pushing: docker scout cves image:tag.

Container Lifecycle

• Containers are ephemeral — do not store state inside them; use volumes or object storage.
• docker logs <container> --tail 50 --follow for live debugging.
• docker exec -it <container> sh for interactive inspection — avoid in production.
• Always set resource limits in production: --memory, --cpus.

Compose

• Use named volumes, not bind mounts, for data that must persist across container restarts.
• Declare depends_on with condition: service_healthy when ordering matters.
• Override production credentials via .env or environment injection — never commit secrets to compose.yml.

Networking

• Use named networks; avoid the default bridge network for multi-container projects.
• Expose ports minimally: prefer internal service names for inter-container communication.
• Do not bind to 0.0.0.0 in production without a firewall rule in place.