Cache Tuning

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

Production recommendations​

Use a persistent cache directory​

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

CACHE_DIR=/data/previewproxy-cache

Cap disk usage​

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

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:

CACHE_MEMORY_MAX_MB=512

TTL guidance​

Memory TTL​

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 CACHE_DISK_TTL_SECS based on how frequently your source images change:

Memory vs disk tradeoffs​

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:
  CACHE_DIR: /data/cache
  CACHE_DISK_MAX_MB: "10240"
  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):

CACHE_MEMORY_MAX_MB=0

Effectively disable L2 (disk cache):

Either set a very short TTL:

CACHE_DISK_TTL_SECS=0

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