Docker Filesystem Cache for Persistent Image Processing

Responsive image processing shouldn't rerun every deployment. Here's how to cache processed images using Docker's filesystem cache mounts, avoiding the slow multi-stage copy pattern.

Static sites need multiple image sizes (thumbnail, small, medium, large) in different formats (WebP, JPEG). Processing hundreds of images from a CMS on every build is wasteful:

  • 5+ minutes of Sharp processing per deploy
  • Redundant work when only content changes
  • Slow feedback loops kill productivity

Filesystem Cache Mounts

Instead of copying processed images between build stages, use --mount=type=cache to persist images across builds:

RUN --mount=type=cache,target=/cache/images,id=processed-images \
    --mount=type=cache,target=/cache/manifest,id=image-manifest \
    echo "🔄 Loading cached images..." && \
    mkdir -p ./static/images/processed && \
    cp -r /cache/images/* ./static/images/processed/ 2>/dev/null || echo "No cached images found" && \
    cp /cache/manifest/image-manifest.json ./static/image-manifest.json 2>/dev/null || echo "No cached manifest found" && \
    echo "🖼️  Starting smart image processing..." && \
    node scripts/process-images-standalone.cjs && \
    echo "💾 Updating cache..." && \
    cp -r ./static/images/processed/* /cache/images/ 2>/dev/null || echo "No new images to cache" && \
    cp ./static/image-manifest.json /cache/manifest/ 2>/dev/null || echo "No manifest to cache"

The image processing script scans Directus for new images and only processes missing files.

Multi-Architecture Strategy

Results

  • 5 minutes → 30 seconds: Cache hits skip image processing entirely
  • Multi-arch builds: ARM64 containers get pre-processed images with files copied from x86 layers
  • Incremental updates: Only new CMS images trigger processing
  • Limited complexity: Standard Docker, no external services

Filesystem cache mounts persist between builds on the same runner, making static site deploys dramatically faster when you're iterating on content rather than infrastructure.