> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Redis Setup Guide
> Provision and operate the two Redis-compatible stores SuprSend needs in self-hosted deployments.
This document explains how to provision and operate the key-value stores SuprSend needs in self-hosted deployments. It covers **two separate stores** (both Redis-compatible), high availability options, Kubernetes/VM installs, configuration, performance, observability, and backups.
***
## Architecture
SuprSend uses Redis-compatible stores in two distinct roles:
1. **Cache Store (non-clustered Redis)**
* Purpose: idempotency keys caching, short-lived/ephemeral data, cross-service temporary data, and uses service-level isolation via **database numbers**.
* **Important:** Do **not** run this in Redis Cluster mode (Cluster mode doesn’t support database numbers).
* Eviction: If needed can be set to `volatile-lru`
2. **Worker State Store (Redis or KV-Rocks)**
* Purpose: queue/worker progress, workflow step state emitted during Temporal-driven execution, retry bookkeeping, etc.
* Durability: recommended (AOF or SSD-backed KV).
* You may use **Redis (standalone/Sentinel/Cluster)** or **KV-Rocks** (Redis-compatible, SSD-optimized) to reduce cost for larger datasets.
We *strongly* recommend using a **managed** service (e.g., AWS ElastiCache, GCP Memorystore, Azure Cache for Redis) for both roles in production. If that’s not possible, you can run them on Kubernetes or VMs (guides below).
***
## Minimum Requirements & Versioning
* **Redis ≥ 7.0** (stable stream), or **KV-Rocks latest stable**.
* TLS support recommended in production.
* For Kubernetes: k8s ≥ 1.25, StorageClass with SSD-backed volumes for the Worker State store.
* Networking: predictable DNS (e.g., `redis-cache.svc.cluster.local`, `redis-state.svc.cluster.local`), security groups/NetworkPolicies.
***
## Instance Sizing
Adjust after observing real traffic. Use `keys`, `memory`, `latency`, and hit/miss ratios to tune.
| Role | CPU | RAM | Storage | Notes |
| ----------------------- | -------: | ------: | --------------: | -------------------------------------------------- |
| Cache Store | 1–2 vCPU | 2–8 GB | 0–10 GB | Disable or minimize persistence, enable eviction. |
| Worker State (Redis) | 2–4 vCPU | 8–32 GB | 50–200 GB SSD | Enable AOF (appendfsync everysec), or use Cluster. |
| Worker State (KV-Rocks) | 2–4 vCPU | 8–32 GB | 200–1000 GB SSD | Designed for large state at lower RAM cost. |
***
## Connection & App Configuration
Set the following environment variables in SuprSend services:
> Since we use DB numbers for isolation, only pass redis url without `/` and database number
* **Cache Store**
* `REDIS_CONN_BASE_URL` — e.g., `redis://:@redis-cache:6379`
* **Worker State Store**
> You can pass full redis connection URL including database number if not running in cluster mode
* `REDIS_WORKERCACHE_CONN_URL` — e.g., `redis://:@redis-state:6379/0` (Redis) or `redis://kvrocks-state:6666/0` (KV-Rocks defaults vary)
> **Do not** point both roles to the same instance. Keep credentials and ACLs separate.
***
## Recommended Configurations
### Cache Store (Standalone Redis, non-cluster)
Key goals: low latency, predictable eviction, minimal persistence.
```
# redis.conf (Cache)
maxmemory 75%
maxmemory-policy allkeys-lru
appendonly no # disable persistence for pure cache
save "" # or disable RDB
timeout 0
aclfile /etc/redis/users.acl # configure users/ACLs
```
### Worker State Store (Redis)
Key goals: durability, predictable recovery, optional scaling via Cluster.
```
# redis.conf (Worker State)
appendonly yes
appendfsync everysec
save 900 1 300 10 60 10000 # optional RDB for faster restarts
timeout 0
# If standalone/Sentinel: one primary + 2 replicas recommended
# If Cluster: 3+ primaries with replicas; mind client-side routing compatibility
```
### Worker State Store (KV-Rocks)
* Use SSD volumes and ensure adequate IOPS.
* Configure compaction and rate-limits per KV-Rocks recommendations.
* Keep memory baseline for memtables/Block cache; rely on SSD for depth.
***
## High Availability Options
* **Managed:** choose Multi-AZ, automatic failover.
* **Kubernetes (Redis Sentinel):** one StatefulSet for primary, another for replicas, and a Sentinel Deployment (or use community/Bitnami Helm charts).
* **Redis Cluster:** shard keys across the cluster; validate client library support (SuprSend components use standard Redis clients—Cluster is fine for **Worker State**, not for **Cache** due to DB numbers requirement).
* **KV-Rocks:** run as a StatefulSet with anti-affinity across nodes and regular snapshots.
***
## Security
* **Auth:** require passwords or ACL users (disable `default` or set strong ACL).
* **TLS:** enable TLS at the endpoint (managed services: turn on “in-transit encryption”).
* **Network:** allowlist only SuprSend namespaces/VMs; use NetworkPolicies/NSGs/SGs.
* **Backups (Worker State):** store encrypted snapshots in object storage; rotate credentials.
***
## Observability and Backup
* Monitor with **redis-exporter** (Prometheus + Grafana).
* Backup Redis AOF/RDB or KV-Rocks snapshots nightly.
* Store backups securely in S3/GCS/Azure Blob.
***
## Managed Services (Recommended)
* AWS ElastiCache (Multi-AZ, in-transit encryption, auto failover)
* GCP Memorystore / Azure Cache equivalents.
* Use private VPC endpoints and IAM-based access control.
***
## Cost Optimization Tips
* Keep **Cache** ephemeral (disable persistence, small RAM, TTLs).
* Use **KV-Rocks** for large Worker State stores.
* Scale horizontally based on ops/sec and latency metrics.
***
## SuprSend Helm Configuration
Once your Redis instances are set up and running, configure SuprSend to use them.
This section shows only the **Redis-specific** configuration. You must also configure other required secrets and values for SuprSend to work properly. See the complete configuration guide: [SuprSend Installation Guide](/docs/self-hosted/suprsend-installation-guide)
### Kubernetes Secret Configuration
First, add the Redis-specific secrets to your [`suprsend-secrets.yaml`](/docs/self-hosted/suprsend-installation-guide#step-5-create-suprsend-secrets):
```yaml theme={"system"}
# ============================================
# Redis Configuration (this guide)
# ============================================
# connection URL for Redis without database-number (e.g., `redis://user:password@host:port` or `rediss://user:password@host:port` with TLS)
redisConnBaseUrlKey: "redis://user:password@redis-cache.infra.svc.cluster.local:6379"
# full connection url (with db-number if applicable) for a Redis database used exclusively for worker caching tasks
redisWorkercacheConnUrlKey: "redis://user:password@redis-state.infra.svc.cluster.local:6379/0"
```
### Helm Values Configuration
Then add the following to your [`suprsend-values.yaml`](/docs/self-hosted/suprsend-installation-guide#step-8-configuration--suprsend-valuesyaml) (along with other required configuration):
```yaml theme={"system"}
# connection URL for Redis without database-number(e.g., `redis://user:password@host:port`)
redisConnBaseUrlKey: "redisConnBaseUrlKey"
# full connection url(with db-number if applicable) for a Redis database used exclusively for worker caching tasks. (e.g., `redis://user:password@host:port/0`)
redisWorkercacheConnUrlKey: "redisWorkercacheConnUrlKey"
```
Redis connection is configured entirely via connection URLs in the secrets. The `redisConnBaseUrlKey` should NOT include a database number (SuprSend will append different DB numbers for service isolation). The `redisWorkercacheConnUrlKey` should include the database number (e.g., `/0`). The above configuration goes under `global.secret` section.
***
## FAQ
Not recommended. Cache and Worker State have different durability and configuration needs.
Optional for **Worker State** only.