Cache Tuning

This page provides guidance on tuning PreviewProxy’s cache for different deployment scenarios.

Production recommendations

Use a persistent cache directory

The default PP_CACHE_DIR of /tmp/previewproxy is wiped on system restart (and sometimes more frequently, depending on your OS or container runtime). Point PP_CACHE_DIR at a persistent volume so the disk cache survives restarts:

PP_CACHE_DIR=/data/previewproxy-cache

Cap disk usage

Without a PP_CACHE_DISK_MAX_MB limit, the disk cache grows without bound. Set a limit appropriate for your available storage:

PP_CACHE_DISK_MAX_MB=10240

Tune memory cache size

A larger L1 cache means more images can be served directly from RAM, reducing latency and disk I/O. Start with the default of 256 MB and increase it based on available RAM and observed cache hit rates:

PP_CACHE_MEMORY_MAX_MB=512

TTL guidance

Memory TTL

PP_CACHE_MEMORY_TTL_SECS of 3600 (1 hour) is appropriate for most workloads. Increase it if your images are stable and you want to maximize RAM hit rates.

Disk TTL

Set PP_CACHE_DISK_TTL_SECS based on how frequently your source images change:

Scenario	Suggested value
Static assets (logos, product images)	`604800` (7 days) or longer
Frequently updated content	`3600` - `86400` (1-24 hours)
Near-real-time content	`300` - `900` (5-15 minutes)

This TTL applies to both the transformed cache and the origin cache. For HTTP sources, the origin cache TTL is overridden by the upstream Cache-Control: max-age or Expires response headers when present, so the upstream server controls freshness automatically.

Memory vs disk tradeoffs

	L1 (memory)	L2 (disk)
Speed	Very fast	Slower (I/O bound)
Persistence	Lost on restart	Survives restarts
Capacity	Limited by RAM	Limited by disk
Suitable for	Hot, frequently accessed images	Long-tail and post-restart warming

Docker volume example

The following Docker Compose snippet configures a persistent cache volume with a 10 GB limit and a 7-day TTL:

volumes:
  - ./cache:/data/cache
environment:
  PP_CACHE_DIR: /data/cache
  PP_CACHE_DISK_MAX_MB: "10240"
  PP_CACHE_DISK_TTL_SECS: "604800" # 7 days

Disabling the cache

There is no single flag to disable caching entirely. Use the following approaches if needed:

Disable L1 (memory cache):

PP_CACHE_MEMORY_MAX_MB=0

Effectively disable L2 (disk cache):

Either set a very short TTL:

PP_CACHE_DISK_TTL_SECS=0

Or point PP_CACHE_DIR at a tmpfs mount so writes are discarded on restart and do not consume persistent storage.