Redis Setup

FrontMCP uses Redis for caching, session storage, and distributed state management.

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/plugins';

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

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

Configuration Example

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

@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