Summary

Optimize Dockerfile and container setup: multi-stage builds, proper volumes, health checks, and security best practices. Provide docs and validation steps.

Source: docs/issues/phase-6-docker-optimization.md

Motivation

• Faster, smaller, and more secure images
• Clear production runtime contract with health checks and minimal surface

Tasks

• Convert Dockerfile to multi-stage with builder/runtime
• Minimize runtime image; ensure only necessary libs/binaries (SQLite/redis client if required)
• Run as non-root; verify file permissions; read-only FS where possible
• Add HEALTHCHECK reflecting /health endpoint
• Define volumes for data/logs/config as needed
• Add Makefile targets for build/test-image
• CI: build image on PR; optional image scan (Trivy) — CI build implemented; Trivy optional and deferred
• Document build/run options, envs, volumes; security notes
• Smoke test: run container locally, hit /health and basic flows

Acceptance Criteria

• Multi-stage Dockerfile with smaller final image
• Health checks pass; volumes documented
• Security practices implemented
• Docs updated; CI build passing

Implementation Summary

Dockerfile

• Multi-stage build: golang:1.23-alpine (builder) → alpine:3.18 (runtime)
• Non-root user appuser:appgroup with restrictive permissions
• HEALTHCHECK hitting /health endpoint
• Volumes: /app/data, /app/logs, /app/config, /app/certs
• OCI labels for documentation

docker-compose.yml

• Read-only filesystem (read_only: true)
• Security options (no-new-privileges, cap_drop: ALL)
• Healthchecks for all services
• PostgreSQL and Redis support

Makefile

• docker-build, docker-run, docker-smoke, docker-stop targets

CI (.github/workflows/docker.yml)

• Builds on PR and push to main/tags
• Multi-arch support (amd64, arm64)
• Smoke test via make docker-smoke
• Publishes to ghcr.io/sofatutor/llm-proxy

Documentation

• README.md Docker section with quick start, volumes, and security notes

References

• Doc: docs/issues/phase-6-docker-optimization.md
• Security: docs/security.md
• Health endpoints: internal/server