Skip to main content
Optimize template builds with caching strategies. Template caching speeds up builds by reusing layers and steps that haven’t changed.

​
Overview

Template caching helps you:
  • Speed up template builds
  • Reduce build costs
  • Reuse unchanged layers
  • Optimize build performance
Template builds use Docker layer caching. Steps that haven’t changed are cached and reused, significantly speeding up rebuilds.

​
How Caching Works

Template builds cache each step:
  • Python
  • JavaScript
from hopx_ai.template import Template

template = Template()
template.from_python_image("3.11-slim")

# These steps are cached if unchanged
template.apt_install("curl", "git")      # Cached if packages unchanged
template.pip_install("numpy", "pandas")  # Cached if packages unchanged
template.set_env("DEBUG", "true")        # Cached if value unchanged

# Only changed steps are rebuilt
template.pip_install("matplotlib")       # Only this step rebuilds if added

​
Skip Cache for Steps

Skip caching for specific steps:
  • Python
  • JavaScript
from hopx_ai.template import Template

template = Template()
template.from_python_image("3.11-slim")

# Install packages (cached)
template.pip_install("numpy", "pandas")

# Run command that should always execute (skip cache)
template.run_cmd("git clone https://github.com/user/repo.git /app")
template.skip_cache()  # Skip cache for previous step

# Next steps are cached again
template.pip_install("flask")

​
Skip Cache for Entire Build

Skip all caching for a build:
  • Python
  • JavaScript
from hopx_ai.template import BuildOptions
import os

# Skip all caching
options = BuildOptions(
    name="my-template",
    api_key=os.getenv("HOPX_API_KEY"),
    skip_cache=True  # Skip all caching
)

# Useful for:
# - Debugging build issues
# - Ensuring fresh builds
# - Testing build steps

​
Optimizing Build Order

Order steps for optimal caching:
  • Python
  • JavaScript
from hopx_ai.template import Template

template = Template()
template.from_python_image("3.11-slim")

# ✅ Good: Stable steps first (cached longer)
template.apt_install("curl", "git")           # Rarely changes
template.pip_install("numpy", "pandas")        # Changes less frequently
template.set_env("NODE_ENV", "production")    # Rarely changes

# ✅ Good: Frequently changing steps last
template.run_cmd("git clone repo /app")       # Changes often
template.run_cmd("cp config.json /app")       # Changes often

# ❌ Bad: Frequently changing steps first
# template.run_cmd("git clone repo /app")     # Invalidates all cache
# template.apt_install("curl")                # Never cached

​
Cache Invalidation

Understand when cache is invalidated:
  • Python
  • JavaScript
from hopx_ai.template import Template

template = Template()
template.from_python_image("3.11-slim")

# Cache is invalidated when:
# 1. Step arguments change
template.pip_install("numpy", "pandas")  # Cached
template.pip_install("numpy", "pandas", "matplotlib")  # Cache invalidated

# 2. Step order changes
template.apt_install("curl")
template.pip_install("numpy")
# vs
template.pip_install("numpy")
template.apt_install("curl")  # Different cache key

# 3. Base image changes
template = create_template("python:3.11-slim")  # One cache
template = create_template("python:3.12-slim")  # Different cache

# 4. Files change (for COPY steps)
# template.copy("/local/src", "/app")  # Cache invalidated if files change

​
Best Practices

1

1. Order Steps by Stability

Place stable steps (system packages, language packages) before frequently changing steps (file copies, git clones).
2

2. Group Related Steps

Group related steps together to maximize cache hits.
3

3. Use skip_cache Sparingly

Only skip cache for steps that must always execute (e.g., git clones with latest changes).
4

4. Minimize Changes

Minimize changes to early steps to preserve cache for later steps.
5

5. Test Cache Behavior

Test builds to understand cache behavior and optimize step ordering.

​
Next Steps