Redis Setup

Deploying to Vercel? Consider Vercel KV for edge-compatible storage without managing Redis infrastructure.

Requirements

Environment	Redis	Notes
Development	Recommended	Enables full feature testing
Production	Required	Essential for multi-instance deployments

Development Setup

Option 1: Docker Compose (Recommended)

Projects created with frontmcp create --target node include Docker files in the ci/ folder:

# Start Redis
docker compose -f ci/docker-compose.yml up redis -d

# Verify Redis is running
docker compose -f ci/docker-compose.yml exec redis redis-cli ping

# Start the full stack (app + Redis)
docker compose -f ci/docker-compose.yml up

When running inside Docker, use redis (the service name) as REDIS_HOST, not localhost. Projects created with frontmcp create include a ci/.env.docker file with Docker-specific values.

Option 2: Local Installation

# macOS
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis

Configuration

import { CachePlugin } from '@frontmcp/plugin-cache';

CachePlugin.init({
  type: 'redis',
  config: {
    host: process.env.REDIS_HOST || 'localhost',
    port: Number(process.env.REDIS_PORT || 6379),
    password: process.env.REDIS_PASSWORD,
    db: parseInt(process.env.REDIS_DB || '0'),
    tls: process.env.REDIS_TLS === 'true',
  }
});

Already configuring the top-level redis block (or redis.provider: 'vercel-kv') on @FrontMcp? Set CachePlugin.init({ type: 'global-store' }) so the plugin automatically reuses that store without duplicating credentials.

For complete CachePlugin API documentation, see the Cache Plugin Guide.

Production Setup

Redis is required in production. Without Redis, session data will be lost on restart and caching will not persist across instances.

Managed Redis Services (Recommended)

Provider	Service
AWS	ElastiCache for Redis
GCP	Memorystore for Redis
Azure	Azure Cache for Redis
Upstash	Serverless Redis
Redis Cloud	Redis Enterprise

Self-Hosted Production

For self-hosted Redis in production:

# docker-compose.prod.yml
services:
  redis:
    image: redis:7-alpine
    command: >
      redis-server
      --appendonly yes
      --requirepass ${REDIS_PASSWORD}
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data
    restart: unless-stopped

Security Best Practices

Authentication: Always set REDIS_PASSWORD in production
Network: Run Redis in private network, not exposed to internet
TLS: Enable TLS for encrypted connections
Persistence: Use AOF for durability (appendonly yes)

Configuration Example

// src/main.ts
import 'reflect-metadata';
import { FrontMcp } from '@frontmcp/sdk';
import { CachePlugin } from '@frontmcp/plugin-cache';

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  redis: {
    host: process.env.REDIS_HOST,
    port: Number(process.env.REDIS_PORT || 6379),
    password: process.env.REDIS_PASSWORD,
    tls: process.env.REDIS_TLS === 'true',
  },
  plugins: [
    CachePlugin.init({
      type: 'global-store',
      defaultTTL: 600,
    }),
  ],
})
export default class Server {}

Switch the redis block to { provider: 'vercel-kv' } when deploying on Vercel KV—the Cache Plugin will keep reusing the same store without code changes.

Environment Variables

Redis Configuration

Variable	Required	Default	Description
`REDIS_HOST`	Yes	`localhost`	Redis server hostname
`REDIS_PORT`	No	`6379`	Redis server port
`REDIS_PASSWORD`	Prod only	-	Redis authentication password
`REDIS_DB`	No	`0`	Redis database number
`REDIS_TLS`	No	`false`	Enable TLS encryption
`REDIS_KEY_PREFIX`	No	`mcp:`	Key prefix for cache namespacing (CachePlugin uses content hashing by default)

Plugin Secrets

Variable	Required	Default	Description
`REMEMBER_SECRET`	Prod only	Auto-generated	Encryption secret for RememberPlugin (32+ byte base64-encoded string)

In development, REMEMBER_SECRET is auto-generated and stored in .frontmcp/remember-secret.json. Add this file to .gitignore. In production, always set REMEMBER_SECRET explicitly to ensure consistent encryption across instances.

Health Checks

import Redis from 'ioredis';

async function checkRedisHealth(): Promise<boolean> {
  const redis = new Redis({
    host: process.env.REDIS_HOST,
    port: Number(process.env.REDIS_PORT || 6379),
    password: process.env.REDIS_PASSWORD,
    lazyConnect: true,
  });

  try {
    await redis.connect();
    await redis.ping();
    await redis.quit();
    return true;
  } catch {
    return false;
  }
}

Troubleshooting

Connection Refused

Verify Redis is running: redis-cli ping
Check firewall rules
Verify host/port configuration

Authentication Failed

Ensure REDIS_PASSWORD matches server config
Check for special characters in password (may need URL encoding)

Memory Issues

Set maxmemory and maxmemory-policy in Redis config
Monitor with redis-cli INFO memory

Docker Network Issues

When using Docker Compose, the app container should use redis as the hostname (the service name), not localhost:

# Inside Docker container
REDIS_HOST=redis

# Outside Docker (local development)
REDIS_HOST=localhost

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Requirements

Development Setup

Option 1: Docker Compose (Recommended)

Option 2: Local Installation

Configuration

Production Setup

Managed Redis Services (Recommended)

Self-Hosted Production

Security Best Practices

Configuration Example

Environment Variables

Redis Configuration

Plugin Secrets

Health Checks

Troubleshooting

Connection Refused

Authentication Failed

Memory Issues

Docker Network Issues

​Requirements

​Development Setup

​Option 1: Docker Compose (Recommended)

​Option 2: Local Installation

​Configuration

​Production Setup

​Managed Redis Services (Recommended)

​Self-Hosted Production

​Security Best Practices

​Configuration Example

​Environment Variables

​Redis Configuration

​Plugin Secrets

​Health Checks

​Troubleshooting

​Connection Refused

​Authentication Failed

​Memory Issues

​Docker Network Issues

Requirements

Development Setup

Option 1: Docker Compose (Recommended)

Option 2: Local Installation

Configuration

Production Setup

Managed Redis Services (Recommended)

Self-Hosted Production

Security Best Practices

Configuration Example

Environment Variables

Redis Configuration

Plugin Secrets

Health Checks

Troubleshooting

Connection Refused

Authentication Failed

Memory Issues

Docker Network Issues