Documentation Index
Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
Use this file to discover all available pages before exploring further.
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:
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
// Conceptual example
const template = new Template('python:3.11-slim');
// These steps are cached if unchanged
template.aptInstall('curl', 'git'); // Cached if packages unchanged
template.pipInstall('numpy', 'pandas'); // Cached if packages unchanged
template.setEnv('DEBUG', 'true'); // Cached if value unchanged
// Only changed steps are rebuilt
template.pipInstall('matplotlib'); // Only this step rebuilds if added
Skip Cache for Steps
Skip caching for specific steps:
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")
// Conceptual example
const template = new Template('python:3.11-slim');
// Install packages (cached)
template.pipInstall('numpy', 'pandas');
// Run command that should always execute (skip cache)
template.runCmd('git clone https://github.com/user/repo.git /app');
template.skipCache(); // Skip cache for previous step
// Next steps are cached again
template.pipInstall('flask');
Skip Cache for Entire Build
Skip all caching for a build:
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
// Conceptual example
const options = new BuildOptions({
name: 'my-template',
apiKey: process.env.HOPX_API_KEY,
skipCache: true // Skip all caching
});
Optimizing Build Order
Order steps for optimal caching:
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
// Conceptual example
const template = new Template('python:3.11-slim');
// ✅ Good: Stable steps first (cached longer)
template.aptInstall('curl', 'git'); // Rarely changes
template.pipInstall('numpy', 'pandas'); // Changes less frequently
template.setEnv('NODE_ENV', 'production'); // Rarely changes
// ✅ Good: Frequently changing steps last
template.runCmd('git clone repo /app'); // Changes often
template.runCmd('cp config.json /app'); // Changes often
Cache Invalidation
Understand when cache is invalidated:
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
// Conceptual example
const template = new Template('python:3.11-slim');
// Cache is invalidated when:
// 1. Step arguments change
template.pipInstall('numpy', 'pandas'); // Cached
template.pipInstall('numpy', 'pandas', 'matplotlib'); // Cache invalidated
// 2. Step order changes
template.aptInstall('curl');
template.pipInstall('numpy');
// vs
template.pipInstall('numpy');
template.aptInstall('curl'); // Different cache key
// 3. Base image changes
const template1 = new Template('python:3.11-slim'); // One cache
const template2 = new Template('python:3.12-slim'); // Different cache
Best Practices
1. Order Steps by Stability
Place stable steps (system packages, language packages) before frequently changing steps (file copies, git clones).
2. Group Related Steps
Group related steps together to maximize cache hits.
3. Use skip_cache Sparingly
Only skip cache for steps that must always execute (e.g., git clones with latest changes).
4. Minimize Changes
Minimize changes to early steps to preserve cache for later steps.
5. Test Cache Behavior
Test builds to understand cache behavior and optimize step ordering.
Next Steps
