Skip to main content

​
Redis Setup

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

​
Requirements

EnvironmentRedisNotes
DevelopmentRecommendedEnables full feature testing
ProductionRequiredEssential for multi-instance deployments

​
Development Setup

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',
  }
});
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.
ProviderService
AWSElastiCache for Redis
GCPMemorystore for Redis
AzureAzure Cache for Redis
UpstashServerless Redis
Redis CloudRedis 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' },
  plugins: [
    CachePlugin.init({
      type: 'redis',
      config: {
        host: process.env.REDIS_HOST,
        port: Number(process.env.REDIS_PORT || 6379),
        password: process.env.REDIS_PASSWORD,
        tls: process.env.REDIS_TLS === 'true',
      },
    }),
  ],
})
export default class Server {}

​
Environment Variables

VariableRequiredDefaultDescription
REDIS_HOSTYeslocalhostRedis server hostname
REDIS_PORTNo6379Redis server port
REDIS_PASSWORDProd only-Redis authentication password
REDIS_DBNo0Redis database number
REDIS_TLSNofalseEnable TLS encryption
REDIS_KEY_PREFIXNomcp:Key prefix for cache namespacing (CachePlugin uses content hashing by default)

​
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