Docker Build & Cache

1. Build Caching Basics

• Docker caches layers based on commands in the Dockerfile.
• To take advantage of caching:
  • Copy dependency files (pyproject.toml, uv.lock, etc.) before source code.
  • Run dependency installation (uv sync, pip install) before copying the app code.
• Cache is reused if the files/commands in a layer haven't changed.

---

2. One-Stage vs Multi-Stage Builds

• One-stage build
  • Simpler, caching still works.
  • Use cleanup commands to reduce image size.
• Multi-stage build
  • Allows separating build environment from runtime.
  • Can remove compilers and build tools from the final image.
  • Slightly more complex but smaller final image.

---

3. Cleaning Up Cache & Temporary Files example

• UV cache cleanup:

  uv cache clean

• Removes only uv’s internal cache.

• Full cleanup:

  RUN rm -rf \
      /root/.cache/pip \
      /root/.cache/uv \
      /tmp/*

  • Removes pip cache, uv cache, and temporary files.

• APT cleanup:

  RUN rm -rf /var/lib/apt/lists/*

---

4. Temporary Build Tools example

• Install build tools only for dependency compilation:

  RUN apt-get install -y build-essential cmake pkg-config \
      && uv sync \
      && apt-get purge -y build-essential cmake pkg-config \
      && apt-get autoremove -y

• Reduces final image size (~150–200MB smaller).

---

5. Build Cache Inspection

• Show total build cache size:

  docker system df

• Detailed view of cache layers:

  docker buildx du --verbose

• Key fields:
  • ID: cache ID
  • SIZE: layer size
  • LAST ACCESSED: last time the layer was used
  • RECLAIMABLE: whether it can be removed safely

---

6. Cache Pruning

• Prune build cache older than a threshold:

  docker buildx prune --filter until=24h

  • Removes layers not accessed in the last 24 hours.
  • Keeps recently used cache for fast incremental builds.
  • Safe to use after deploys to remove stale layers.

---

7. Safe Deploy Script (Cache-Friendly)

docker compose down --rmi local --remove-orphans
docker compose up -d --remove-orphans
docker buildx prune --filter until=24h

• Removes unused local images only, keeping referenced images.
• Starts containers using cached layers.
• Removes stale build cache older than 24 hours.

---

8. Tips for Smaller Images

1. Use python:3.13-slim or alpine base images.
2. Install build tools temporarily, then purge them.
3. Clean uv & pip caches after installs.
4. Remove temporary files (/tmp/*) and apt lists (/var/lib/apt/lists/*).
5. Order Dockerfile commands to maximize cache hits.

9. Inspect why the built image is big

docker image ls docker history <image-id>

or

docker run --rm -it <image-id> du -h -d1 /

to see which directories are eating space.