Pull-Through Cache

Drevnix can cache Docker image blobs (layers) on local disk. Once a layer is cached, subsequent pulls of the same layer are served from disk rather than fetching from the upstream registry, reducing bandwidth consumption and improving pull latency.

What is cached: Image layers (blobs), identified by content digest. Manifests and tags are not cached. Only binary layer data is cached.

Cache availability is controlled by your license.

Enabling the cache

Set these environment variables and restart:

CACHE_ENABLED=true
CACHE_DIR=/data/cache
CACHE_MAX_SIZE_BYTES=53687091200

Always mount a volume for CACHE_DIR. If the cache directory is not mounted, cached blobs accumulate inside the container’s writable layer. When the container is replaced or recreated, all cached data is lost and has to be fetched from upstream again. Worse, the dead container is not immediately deleted by Docker or your orchestrator - its writable layer (containing the cache) stays on disk until garbage collection runs. If your cache is large and GC is slow, this can consume significant disk on the host until the old container is cleaned up. Mount a named volume or a host path so the cache persists across container lifecycles and is not tied to any specific container.

docker run \
  -e CACHE_ENABLED=true \
  -e CACHE_DIR=/data/cache \
  -e CACHE_MAX_SIZE_BYTES=53687091200 \
  -v drevnix-data:/data \
  registry.gitlab.com/drevnix-group/drevnix:1.6

The cache directory does not need to be on fast storage. It is read and written sequentially during pulls, and the admission policy (see below) means only frequently-accessed layers land there.

How the admission policy works

Drevnix does not cache every blob on first pull. A blob only becomes cacheable after it is requested enough times within a time window. This prevents infrequently-pulled images from filling the disk.

Default thresholds (either condition admits the blob):

Window	Threshold
Short (10 minutes)	3 or more hits
Long (1 hour)	10 or more hits

You can tune these with CACHE_MIN_HITS_SHORT, CACHE_WINDOW_SHORT_SECONDS, CACHE_MIN_HITS_LONG, and CACHE_WINDOW_LONG_SECONDS. For a small team where even a single repeat pull should be cached, set CACHE_MIN_HITS_SHORT=1.

LRU eviction

When the cache reaches CACHE_MAX_SIZE_BYTES, the least recently accessed blobs are evicted to make room. The portal’s Cache page shows current disk usage so you can monitor and adjust the limit.

TTL

Cached blobs expire after CACHE_ENTRY_TTL_SECONDS (default: 86400 seconds = 24 hours). After expiry, the next pull re-fetches from upstream and resets the admission counter.

Managing the cache from the portal

Go to Cache in the admin portal to:

• View disk usage (used vs. maximum)
• See the total number of cached entries and any in-progress writes
• Browse individual cached blobs (upstream, size, last accessed, expiry)
• Clear all cached blobs (with confirmation)

Sizing guidance

A typical compressed Docker image layer is 50MB-1GB. For parallel CI pipelines:

Team size	Suggested cache size	CACHE_MAX_SIZE_BYTES value
1-10 pipelines	50 GB	53687091200
10-50 pipelines	200 GB	214748364800
50+ pipelines	500 GB+	536870912000

Start conservatively, monitor usage in the portal, and increase CACHE_MAX_SIZE_BYTES as needed. Disk is cheap; upstream bandwidth and pull latency are not.