Skip to main content

⬅️ Back to Project Overview

Dockerfiles & Compose: Security, Reproducibility, Best Practices

This document details the hardening and best practices applied to all Dockerfiles, Compose files, and related automation for ShieldCraft AI.

1. Hardened Dockerfiles​

  • Multiple Dockerfiles:
  • Distroless & Minimal Images:
    • All production images use Google Distroless or Alpine/slim variants for minimal attack surface
    • No shell or package manager in final images
  • Multi-Stage Builds:
    • Build dependencies and tools are only present in intermediate stages (Multi-stage Docker Builds)
    • Final images contain only runtime and app code
  • Security:
  • Reproducibility:
    • All base images and dependencies are pinned to specific versions
    • .dockerignore excludes unnecessary files (tests, docs, local configs)
    • Build args and environment variables for dev, staging, and prod
  • Best Practices:
    • HEALTHCHECK defined for all services (API, ingestion, etc.)
    • Layer caching optimized for fast builds and CI/CD
    • Image size minimized for fast deploys and reduced attack surface
    • Labels and metadata for traceability

2. Docker Compose & Environments​

  • Three Environments:
    • dev: Local development with hot-reload, debug tools, and test data
    • staging: Mirrors production, used for integration and pre-release testing
    • prod: Hardened, minimal, and monitored for production workloads
  • Service Isolation:
    • Separate services for API, ingestion, vector DB, etc.
    • Network segmentation, explicit port mappings, and no unnecessary inter-service communication (Docker Compose Networking)
  • Security:
    • No privileged containers; drop all unnecessary Linux capabilities
    • Environment variables and secrets managed via .env and external secrets store
    • Volumes and mounts restricted to only what is needed (Docker Volumes)
    • Read-only root filesystem where possible (Read-only Filesystem)
  • Reproducibility:
    • Compose files versioned, peer-reviewed, and environment-specific overrides
    • Consistent local and CI/CD builds
    • Automated smoke tests after build/deploy (Smoke Testing

3. Nox & Automation​

  • Noxfile orchestrates:
    • Nox for linting, testing, building, and running containers for all environments
    • Automated checks for Dockerfile and Compose best practices
    • Integration with pre-commit hooks and CI/CD pipelines
    • Automated vulnerability scans and dependency updates

4. Continuous Improvement​

  • Regular reviews of Dockerfiles and Compose for new vulnerabilities and optimizations
  • Automated dependency updates and security patching
  • Documentation for onboarding, troubleshooting, and environment setup
  • Incident response: Documented process for patching and rolling out new images in case of CVEs (CVE Details)

Next Steps​

  • Review and update Dockerfiles and Compose files for new vulnerabilities and optimizations
  • Automate dependency updates and security patching in CI/CD
  • Document onboarding, troubleshooting, and environment setup
  • Maintain incident response process for CVEs and image patching