> For the complete documentation index, see [llms.txt](https://docs.zerve.ai/self-managed/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zerve.ai/self-managed/configuration/redis.md).

# Redis

Zerve uses [Redis](https://redis.io/) for a variety of internal functions: inter-service message passing, queues, caching, workflow orchestration. Several deployment options are supported.

One instance serves the whole platform — each service keeps its data in its own logical database.

## Bundled Redis

The chart may install Redis for you. It is meant for evaluation and testing only: a single replica, with no high availability, failover or TLS.

Persistence is also off by default, so a pod restart drops in-flight background jobs along with the message broker streams and caches. Set `redis.persistence.enabled: true` for an append-only file on a PVC if you need queues to survive restarts.

Setting `redis.enabled: true` creates the instance, but the services still read `REDIS_*` from their own environment. The chart ships a values file with that wiring already in place, so layer it on top of your own values and keep it last:

```
helm upgrade --install zerve . -f my-values.yaml -f examples/bundled-redis.yaml
```

For production, we recommend an external Redis managed outside the cluster.

## External Redis

Point the platform at your instance in the Helm chart:

```yaml
# my-values.yaml
global:
  workload:
    common:
      env:
        REDIS_HOST: "redis.acme.internal"
        REDIS_PORT: "6379"                        # optional
        REDIS_TLS_ENABLED: "true"                 # optional, off unless set
```

Values under `global` propagate to all backend workloads.

## Authentication

Zerve sends `AUTH` when a password is configured. Supply it as a Secret reference rather than a literal value:

```yaml
# my-values.yaml
global:
  workload:
    common:
      secrets:
        REDIS_PASSWORD:
          secretName: zerve-creds
          key: redis_password                     # optional, defaults to REDIS_PASSWORD
      env:
        REDIS_USERNAME: "zerve"                   # optional, ACL users only
```

Set `REDIS_USERNAME` only if your server authenticates named ACL users. On a server using `requirepass`, the password alone identifies the connection and the username must stay unset.

Authentication is optional, and a password is not a substitute for network isolation. We recommend restricting network access to Redis and admit only Zerve workload traffic.

## TLS

`REDIS_TLS_ENABLED: "true"` connects over `rediss://`. On its own that encrypts the connection but does not check who is on the other end: whether the server's certificate is verified is governed separately by `REDIS_SSL_CERT_REQS`.

| `REDIS_SSL_CERT_REQS` | Behaviour                                                  |
| --------------------- | ---------------------------------------------------------- |
| `none` (default)      | The server certificate is accepted without verification.   |
| `optional`            | A certificate is verified if the server presents one.      |
| `required`            | The server must present a certificate, and it must verify. |

Set it to `required` for a production instance:

```yaml
# my-values.yaml
global:
  workload:
    common:
      env:
        REDIS_TLS_ENABLED: "true"
        REDIS_SSL_CERT_REQS: "required"
```

A certificate issued by a public CA verifies against the system trust store with no further configuration. For a certificate from a private or internal CA, mount your CA bundle and point `REDIS_SSL_CA_CERT_PATH` at it.

The certificate is verified against the CA; its hostname is not matched against the host Zerve connected to.

### Client certificates

For a server that requires mutual TLS, mount the client certificate and its private key and set both paths:

```yaml
REDIS_SSL_CERT_PATH: "/etc/zerve/redis-tls/client.crt"
REDIS_SSL_KEY_PATH: "/etc/zerve/redis-tls/client.key"
```

Both are required, even when the key is also bundled into the certificate file. Setting one without the other fails at startup rather than connecting without the certificate.

### Mounting certificate files

Redis is used by the canvas, executor and user services. Each takes its own volume definitions, so put the files in a Secret and declare the volume on all three:

```yaml
# my-values.yaml
canvas:
  volumes:
    redisTls:
      name: redis-tls
      mountPath: /etc/zerve/redis-tls
      readOnly: true
      source:
        secret:
          secretName: zerve-redis-tls             # keys become filenames
  workloads:
    common:
      extraVolumes: [redisTls]
    # The canvas worker and message listener carry their own extraVolumes list,
    # which replaces the one above rather than adding to it. Repeat both entries
    # here, or these two workloads start without the certificates — and without
    # the scratch space they need on a read-only root filesystem.
    worker:
      extraVolumes: [tmpDir, redisTls]
    msgListener:
      extraVolumes: [tmpDir, redisTls]

executor:
  volumes:
    redisTls:
      name: redis-tls
      mountPath: /etc/zerve/redis-tls
      readOnly: true
      source:
        secret:
          secretName: zerve-redis-tls
  workloads:
    common:
      extraVolumes: [redisTls]

user:
  volumes:
    redisTls:
      name: redis-tls
      mountPath: /etc/zerve/redis-tls
      readOnly: true
      source:
        secret:
          secretName: zerve-redis-tls
  workloads:
    common:
      extraVolumes: [redisTls]
```

With a `zerve-redis-tls` Secret holding `ca.crt`, `client.crt` and `client.key`, the paths are then `/etc/zerve/redis-tls/ca.crt` and so on.

The user service also ships a predefined `caBundle` volume, which mounts a `ca-bundle` Secret over the system trust store at `/etc/ssl/certs/ca-certificates.crt`. If you already use it to trust an internal CA for outbound TLS, that path works for `REDIS_SSL_CA_CERT_PATH` too.

The `REDIS_SSL_*` paths are only read when `REDIS_TLS_ENABLED` is true. Setting them with TLS off fails at startup, so a certificate is never silently left unused.

## Message broker

The canvas and executor services run their message broker on Redis streams. Both default `MSG_BROKER_REDIS_HOST` to `REDIS_HOST`, so the streams land on the same instance as the queues and caches without further configuration.

The host is all that carries over. Every other setting on this page has a `MSG_BROKER_REDIS_` counterpart that defaults independently, so a broker sharing an authenticated or TLS instance needs them repeated:

```yaml
# my-values.yaml
canvas:
  workloads:
    common:
      secrets:
        MSG_BROKER_REDIS_PASSWORD:
          secretName: zerve-creds
          key: redis_password
      env:
        MSG_BROKER_REDIS_TLS_ENABLED: "true"
        MSG_BROKER_REDIS_SSL_CERT_REQS: "required"

executor:
  workloads:
    common:
      secrets:
        MSG_BROKER_REDIS_PASSWORD:
          secretName: zerve-creds
          key: redis_password
      env:
        MSG_BROKER_REDIS_TLS_ENABLED: "true"
        MSG_BROKER_REDIS_SSL_CERT_REQS: "required"
```

To keep broker traffic on a separate instance, set `MSG_BROKER_REDIS_HOST` on the two services as well:

```yaml
# my-values.yaml
canvas:
  workloads:
    common:
      env:
        MSG_BROKER_REDIS_HOST: "broker-redis.acme.internal"
        MSG_BROKER_REDIS_PORT: "6379"
        MSG_BROKER_REDIS_TLS_ENABLED: "true"

executor:
  workloads:
    common:
      env:
        MSG_BROKER_REDIS_HOST: "broker-redis.acme.internal"
        MSG_BROKER_REDIS_PORT: "6379"
        MSG_BROKER_REDIS_TLS_ENABLED: "true"
```

Both `canvas` and `executor` services must point at the same broker instance and the same logical database, or they will not see each other's messages.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zerve.ai/self-managed/configuration/redis.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.