> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Pull the official Cache-Pot Docker image, mount a data volume for persistence, and configure via environment variables in a docker-compose.yml.

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:

```bash theme={null}
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:

```bash theme={null}
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.

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

## 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:

```bash theme={null}
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.

```yaml docker-compose.yml theme={null}
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:

```bash theme={null}
docker compose up -d
```

Check that it is running and healthy:

```bash theme={null}
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)
```

<Warning>
  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.
</Warning>

## 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                           |

<Info>
  `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.
</Info>