Redis

Overview

Redis is an in-memory data structure store used as a database, cache, and message broker. Convox supports both containerized Redis and AWS ElastiCache-managed instances.

Basic Configuration

Define a Redis resource in convox.yml:

resources:
  cache:
    type: redis

services:
  web:
    resources:
      - cache

Containerized Redis

For development and staging environments, use containerized Redis:

resources:
  cache:
    type: redis

Custom Images

Use custom Redis images:

resources:
  cache:
    type: redis
    image: redis:7-alpine

The image field allows you to use any compatible Redis image. Always include an image tag.

AWS ElastiCache Redis

For production workloads, use AWS ElastiCache for enhanced durability, high availability, and managed operations:

resources:
  cache:
    type: elasticache-redis
    options:
      class: cache.t3.micro
      version: "6.2"
      deletionProtection: true
      durable: true
      encrypted: true

Configuration Options

class

string

required

The compute and memory capacity of the cache node. Common values:

cache.t3.micro - 0.5 GiB memory
cache.t3.small - 1.37 GiB memory
cache.t3.medium - 3.09 GiB memory
cache.m5.large - 6.38 GiB memory
cache.r5.large - 13.07 GiB memory (memory-optimized)

version

string

required

Redis engine version (e.g., 6.2, 7.0, 7.1)

deletionProtection

boolean

default:"false"

Prevent accidental deletion of the cache cluster. This is a Convox-managed feature that prevents resource removal even if deleted from convox.yml.

durable

boolean

default:"false"

Create a Multi-AZ deployment with automatic failover for high availability

encrypted

boolean

default:"false"

Enable encryption at rest for data stored on disk

transitEncryption

boolean

default:"false"

Enable in-transit encryption (TLS) for data flowing between your application and Redis

autoMinorVersionUpgrade

boolean

default:"true"

Automatically apply minor engine version patches during maintenance windows

import

string

ElastiCache replication group ID to import an existing cluster

deletionProtection is a Convox feature, not an AWS feature. It prevents the resource from being deleted if removed from convox.yml.

Advanced Features

Import Existing ElastiCache

Import an existing AWS ElastiCache Redis cluster:

resources:
  imported-cache:
    type: elasticache-redis
    options:
      import: my-existing-redis-cluster

services:
  web:
    resources:
      - imported-cache

import

string

The replication group ID of the existing ElastiCache Redis cluster

While import is set, the cache cluster is read-only from Convox’s perspective. Remove import to allow Convox to manage the cluster configuration.

High Availability Configuration

For production workloads, enable Multi-AZ with automatic failover:

resources:
  cache:
    type: elasticache-redis
    options:
      class: cache.m5.large
      version: "7.0"
      durable: true
      encrypted: true
      transitEncryption: true
      deletionProtection: true

Encryption Configuration

Enable both at-rest and in-transit encryption:

resources:
  cache:
    type: elasticache-redis
    options:
      class: cache.t3.medium
      version: "6.2"
      encrypted: true
      transitEncryption: true

When transitEncryption is enabled, your Redis connection URL will use rediss:// (Redis with TLS) instead of redis://.

Environment Variables

When linked to a service, Redis resources inject these environment variables:

CACHE_URL=redis://hostname:6379
CACHE_HOST=hostname
CACHE_PORT=6379

For ElastiCache with transit encryption enabled:

CACHE_URL=rediss://hostname:6379

CLI Operations

List Resources

$ convox resources -a myapp
NAME   TYPE               URL
cache  elasticache-redis  redis://hostname:6379

Get Resource Information

$ convox resources info cache -a myapp
Name  cache
Type  elasticache-redis
URL   redis://hostname:6379

Proxy to Redis

Create a local tunnel to the Redis instance:

$ convox resources proxy cache -a myapp
Proxying localhost:6379 to hostname:6379

Connect using redis-cli:

redis-cli -h localhost -p 6379

The proxy command is particularly useful for ElastiCache instances that are not publicly accessible.

Connection Examples

Node.js
Python
Ruby
Go

const redis = require('redis');

const client = redis.createClient({
  url: process.env.CACHE_URL
});

await client.connect();

await client.set('key', 'value');
const value = await client.get('key');

import redis
import os

r = redis.from_url(os.environ['CACHE_URL'])

r.set('key', 'value')
value = r.get('key')

require 'redis'

redis = Redis.new(url: ENV['CACHE_URL'])

redis.set('key', 'value')
value = redis.get('key')

package main

import (
    "github.com/go-redis/redis/v8"
    "os"
)

func main() {
    opt, _ := redis.ParseURL(os.Getenv("CACHE_URL"))
    client := redis.NewClient(opt)
    
    client.Set(ctx, "key", "value", 0)
    val, _ := client.Get(ctx, "key").Result()
}

Production Best Practices

Enable Deletion Protection

Set deletionProtection: true to prevent accidental deletion of production cache clusters.

Use Multi-AZ

Enable durable: true for automatic failover and high availability in production.

Enable Encryption

Use both encrypted: true and transitEncryption: true for comprehensive data protection.

Right-Size Your Instances

Monitor memory usage and choose appropriate cache node types (use r5 family for memory-intensive workloads).

Common Use Cases

Session Storage

Store user sessions with automatic expiration and fast access times.

Application Cache

Cache database queries, API responses, and computed results to reduce latency.

Rate Limiting

Implement rate limiting using Redis counters with expiration.

Job Queues

Use Redis as a message broker for background job processing (with libraries like Sidekiq, Bull, etc.).

Example Configurations

Development
Staging
Production

resources:
  cache:
    type: redis

services:
  web:
    resources:
      - cache

resources:
  cache:
    type: elasticache-redis
    options:
      class: cache.t3.small
      version: "7.0"
      encrypted: true

services:
  web:
    resources:
      - cache

resources:
  cache:
    type: elasticache-redis
    options:
      class: cache.m5.large
      version: "7.0"
      deletionProtection: true
      durable: true
      encrypted: true
      transitEncryption: true
      autoMinorVersionUpgrade: true

services:
  web:
    resources:
      - cache
  worker:
    resources:
      - cache

Primitives

App Primitives

Resources

CLI Reference

Overview

Basic Configuration

Containerized Redis

Custom Images

AWS ElastiCache Redis

Configuration Options

Advanced Features

Import Existing ElastiCache

High Availability Configuration

Encryption Configuration

Environment Variables

CLI Operations

List Resources

Get Resource Information

Proxy to Redis

Connection Examples

Production Best Practices

Enable Deletion Protection

Use Multi-AZ

Enable Encryption

Right-Size Your Instances

Common Use Cases

Session Storage

Application Cache

Rate Limiting

Job Queues

Example Configurations

Build docs developers (and LLMs) love

Primitives

App Primitives

Resources

CLI Reference

​Overview

​Basic Configuration

​Containerized Redis

​Custom Images

​AWS ElastiCache Redis

​Configuration Options

​Advanced Features

​Import Existing ElastiCache

​High Availability Configuration

​Encryption Configuration

​Environment Variables

​CLI Operations

​List Resources

​Get Resource Information

​Proxy to Redis

​Connection Examples

​Production Best Practices

Enable Deletion Protection

Use Multi-AZ

Enable Encryption

Right-Size Your Instances

​Common Use Cases

Session Storage

Application Cache

Rate Limiting

Job Queues

​Example Configurations

Build docs developers (and LLMs) love

Overview

Basic Configuration

Containerized Redis

Custom Images

AWS ElastiCache Redis

Configuration Options

Advanced Features

Import Existing ElastiCache

High Availability Configuration

Encryption Configuration

Environment Variables

CLI Operations

List Resources

Get Resource Information

Proxy to Redis

Connection Examples

Production Best Practices

Common Use Cases

Example Configurations