Run Cache-Pot with Docker: images, volumes, and Compose

Cache-Pot ships a minimal Docker image based on a distroless/static base — there is no shell, no package manager, and no runtime overhead beyond the Go binary itself. Run it with a single docker run command, or compose it alongside your application, database, and other services using a standard docker-compose.yml.

Quick start

Pull the latest image and expose both the RESP2 port and the dashboard:

docker run -p 6379:6379 -p 8080:8080 ghcr.io/subh05sus/cache-pot:latest

Cache-Pot starts immediately. Open http://localhost:8080 for the live dashboard and connect on port 6379 with any Redis client.

With persistence

By default, Cache-Pot persists data to cache-pot.snapshot in the working directory inside the container. Mount a named volume so your data survives container restarts and image updates:

docker run -p 6379:6379 -p 8080:8080 \
  -v cache-pot-data:/data \
  -e CACHEPOT_SNAPSHOT_PATH=/data/cache-pot.snapshot \
  -e CACHEPOT_AOF_PATH=/data/cache-pot.aof \
  ghcr.io/subh05sus/cache-pot:latest

With both snapshot and AOF enabled, Cache-Pot takes periodic snapshots and also writes every mutation to the append-only file. On restart it replays the AOF (which is the more up-to-date source) and compacts it automatically on graceful shutdown.

/data is the recommended volume mount path in Docker deployments. Use it consistently across snapshot, AOF, and any other file-backed options.

With authentication

Set a password using the CACHEPOT_AUTH environment variable. Any Redis client that connects must then call AUTH <password> before issuing other commands:

docker run -p 6379:6379 -p 8080:8080 \
  -e CACHEPOT_AUTH=mysecretpassword \
  ghcr.io/subh05sus/cache-pot:latest

Docker Compose

The following docker-compose.yml brings up Cache-Pot with persistence, authentication, and semantic caching enabled. Environment variables for secrets are read from your shell or a .env file so credentials never live in the Compose file itself.

docker-compose.yml

version: '3.8'

services:
  cache-pot:
    image: ghcr.io/subh05sus/cache-pot:latest
    ports:
      - "6379:6379"
      - "8080:8080"
    volumes:
      - cache-pot-data:/data
    environment:
      CACHEPOT_AUTH: "${CACHE_POT_PASSWORD:-}"
      CACHEPOT_SNAPSHOT_PATH: /data/cache-pot.snapshot
      CACHEPOT_SNAPSHOT_INTERVAL: 60s
      CACHEPOT_AOF_PATH: /data/cache-pot.aof
      CACHEPOT_AOF_FSYNC: everysec
      CACHEPOT_EMBED_URL: "${OPENAI_BASE_URL:-}"
      CACHEPOT_EMBED_KEY: "${OPENAI_API_KEY:-}"
      CACHEPOT_EMBED_MODEL: text-embedding-3-small
    restart: unless-stopped

volumes:
  cache-pot-data:

Start it in detached mode:

docker compose up -d

Check that it is running and healthy:

docker compose logs cache-pot
# cache-pot: listening on [::]:6379
# cache-pot: dashboard on http://localhost:8080
# cache-pot: semantic cache embeddings enabled via CACHEPOT_EMBED_URL  (if embed vars set)

The dashboard on port 8080 is unauthenticated. Do not expose it publicly without placing a reverse proxy or firewall rule in front of it. In production, bind it to 127.0.0.1 or omit the port mapping entirely and access it through a tunnel or internal network.

Environment variables reference

Every Cache-Pot option is available as a CACHEPOT_* environment variable. Each one mirrors a CLI flag of the same shape.

Environment variable	Default	Description
`CACHEPOT_ADDR`	`:6379`	TCP address and port for the RESP2 server
`CACHEPOT_AUTH`	(empty — no auth)	Require clients to authenticate with this password
`CACHEPOT_SNAPSHOT_PATH`	`cache-pot.snapshot`	Path for the periodic snapshot file; set to empty to disable
`CACHEPOT_SNAPSHOT_INTERVAL`	`60s`	How often to write a snapshot to disk
`CACHEPOT_AOF_PATH`	(empty — disabled)	Path for the append-only file; set to enable crash-safe writes
`CACHEPOT_AOF_FSYNC`	`everysec`	fsync policy for the AOF: `always`, `everysec`, or `no`
`CACHEPOT_SWEEP_INTERVAL`	`10s`	How often the background expiry sweeper runs
`CACHEPOT_DASHBOARD_ADDR`	`:8080`	Address for the web dashboard; set to empty to disable
`CACHEPOT_EMBED_URL`	(empty — disabled)	Embeddings endpoint URL for the semantic cache (e.g. `https://api.openai.com/v1/embeddings`)
`CACHEPOT_EMBED_MODEL`	`text-embedding-3-small`	Embedding model name to send in API requests
`CACHEPOT_EMBED_KEY`	(empty)	API key for the embeddings endpoint
`CACHEPOT_MCP_ADDR`	`localhost:6379`	Target address used by `cache-pot mcp` to reach the running server

CACHEPOT_EMBED_URL and CACHEPOT_EMBED_KEY are only needed if you plan to use SCACHE.GET / SCACHE.SET or the MCP search tool. All other features work without an embeddings provider.

Get Started

Core Concepts

Configuration

Guides

Dashboard

Run Cache-Pot with Docker: images, volumes, and Compose

Quick start

With persistence

With authentication

Docker Compose

Environment variables reference

​Quick start

​With persistence

​With authentication

​Docker Compose

​Environment variables reference

Quick start

With persistence

With authentication

Docker Compose

Environment variables reference