Skip to main content
Gorkie uses Redis for caching user permissions and managing application state. This guide covers setting up Redis for both local development and production.

​
Why Redis?

Redis is used in Gorkie for:
  • User Permission Caching: Caches allowed users to reduce Slack API calls
  • Application State: Stores runtime state for distributed deployments
  • Future Features: Rate limiting, session management, and more
Redis is a required dependency. The application will not start without a valid REDIS_URL.

​
Local Development

The fastest way to run Redis locally: 
# Start Redis in Docker
docker run -d \
  --name gorkie-redis \
  -p 6379:6379 \
  redis:7-alpine

# Set environment variable
echo 'REDIS_URL="redis://localhost:6379"' >> .env
Stop Redis: 
docker stop gorkie-redis
Restart Redis: 
docker start gorkie-redis

​
Option 2: Native Installation

​
macOS (Homebrew)

# Install Redis
brew install redis

# Start Redis service
brew services start redis

# Or run Redis manually
redis-server

​
Ubuntu/Debian

# Install Redis
sudo apt update
sudo apt install redis-server

# Start Redis service
sudo systemctl start redis-server
sudo systemctl enable redis-server

​
Windows (WSL)

Install Redis through WSL using the Ubuntu instructions above, or use Docker.

​
Verify Local Installation

# Test connection
redis-cli ping
# Should return: PONG

# Or test with the connection URL
redis-cli -u redis://localhost:6379 ping

​
Production Setup

​
Cloud Redis Providers

1

Create an account

Sign up at https://upstash.com
2

Create a Redis database

  1. Click “Create Database”
  2. Choose a region close to your deployment
  3. Select “Free” or “Pay as you Go” plan
3

Get connection URL

Copy the connection URL from the database details page.
REDIS_URL="rediss://default:[email protected]:6379"
Pros:
  • Generous free tier
  • Serverless pricing model
  • TLS/SSL by default
  • Global edge caching

​
Redis Cloud

1

Create an account

Sign up at https://redis.com/try-free/
2

Create a subscription

  1. Click “New Subscription”
  2. Select cloud provider and region
  3. Choose “Fixed” or “Flexible” plan
3

Create a database

  1. Click “New Database”
  2. Configure memory limit and options
  3. Copy the connection URL
REDIS_URL="redis://default:[email protected]:12345"
Pros:
  • Official Redis Cloud service
  • 30MB free tier
  • High availability options
  • Advanced features (clustering, modules)

​
Railway

If deploying on Railway:
1

Add Redis plugin

In your Railway project, click “New” → “Database” → “Add Redis”
2

Automatic configuration

Railway automatically sets the REDIS_URL environment variable.

​
Render

If deploying on Render:
1

Create Redis instance

  1. Click “New” → “Redis”
  2. Choose a name and region
  3. Select plan (free tier available)
2

Link to web service

  1. Go to your web service settings
  2. Add REDIS_URL environment variable
  3. Use the Internal Redis URL from the Redis instance

​
Self-Hosted Redis

For VPS or self-hosted deployments:

​
Basic Setup

# Install Redis (Ubuntu/Debian)
sudo apt update
sudo apt install redis-server

# Configure Redis
sudo nano /etc/redis/redis.conf
Recommended configuration changes: 
# Bind to localhost only (if app is on same server)
bind 127.0.0.1

# Set a password
requirepass your-strong-password-here

# Enable persistence
save 900 1
save 300 10
save 60 10000

# Set memory limit
maxmemory 256mb
maxmemory-policy allkeys-lru
Restart Redis: 
sudo systemctl restart redis-server
Connection URL: 
REDIS_URL="redis://:your-strong-password-here@localhost:6379"

​
Secure Remote Access

If Redis is on a different server: 
# Allow remote connections (use with firewall)
bind 0.0.0.0

# Require password
requirepass your-strong-password-here

# Optional: Enable TLS (requires stunnel or Redis 6+)
tls-port 6380
port 0
tls-cert-file /path/to/redis.crt
tls-key-file /path/to/redis.key
tls-ca-cert-file /path/to/ca.crt
Never expose Redis to the public internet without authentication and TLS. Use a firewall to restrict access to trusted IPs.

​
Connection String Format

Gorkie uses Bun’s RedisClient which accepts standard Redis URLs.

​
Basic Format

REDIS_URL="redis://host:port"

​
With Authentication

REDIS_URL="redis://:password@host:port"
# or
REDIS_URL="redis://username:password@host:port"

​
With SSL/TLS

REDIS_URL="rediss://username:password@host:port"
Note the rediss:// protocol (with double ‘s’) for secure connections.

​
With Database Number

REDIS_URL="redis://host:port/1"
Default is database 0. Gorkie doesn’t require a specific database number.

​
Usage in Gorkie

Gorkie’s Redis client is defined in server/lib/kv.ts: 
import { RedisClient } from 'bun';
import { env } from '~/env';

export const redis = new RedisClient(env.REDIS_URL);
The client is used throughout the application for caching.

​
User Permission Caching

Defined in server/lib/allowed-users.ts, Gorkie caches Slack workspace members to reduce API calls: 
// Cache user permissions
await redis.set(`allowed:${userId}`, 'true', 3600);

// Check cache
const allowed = await redis.get(`allowed:${userId}`);

​
Data Structures

Gorkie primarily uses:
  • Strings: Simple key-value pairs for caching
  • Expiration: TTL for automatic cache invalidation

​
Testing Redis Connection

​
From Command Line

# Test connection
redis-cli -u "$REDIS_URL" ping

# Check info
redis-cli -u "$REDIS_URL" info server

# Set and get a test value
redis-cli -u "$REDIS_URL" set test "hello"
redis-cli -u "$REDIS_URL" get test

​
From Bun REPL

// Start Bun REPL
// bun repl

import { RedisClient } from 'bun';

const redis = new RedisClient('redis://localhost:6379');
await redis.ping(); // Should return 'PONG'

await redis.set('test', 'hello');
await redis.get('test'); // Should return 'hello'

​
Monitoring

​
Check Memory Usage

redis-cli -u "$REDIS_URL" info memory

​
View All Keys

# Count keys
redis-cli -u "$REDIS_URL" dbsize

# List keys (use with caution in production)
redis-cli -u "$REDIS_URL" keys "*"

​
Monitor Commands

# Watch all commands in real-time
redis-cli -u "$REDIS_URL" monitor

​
Troubleshooting

​
Connection Refused

Error: Connection refused
Solutions:
  • Check Redis is running: redis-cli ping
  • Verify host and port in REDIS_URL
  • Check firewall rules

​
Authentication Failed

Error: NOAUTH Authentication required
Solutions:
  • Include password in URL: redis://:password@host:port
  • Verify password is correct
  • Check Redis requirepass configuration

​
SSL/TLS Errors

Error: SSL connection failed
Solutions:
  • Use rediss:// (with double ‘s’) for SSL
  • Verify certificate is valid
  • Check if Redis has TLS enabled

​
Memory Issues

Error: OOM command not allowed when used memory > 'maxmemory'
Solutions:
  • Increase Redis memory limit
  • Set eviction policy: maxmemory-policy allkeys-lru
  • Clear old keys manually

​
Best Practices

Use SSL/TLS (rediss://) for production deployments
Set strong passwords for Redis authentication
Configure maxmemory and eviction policies
Enable persistence (RDB or AOF) for important data
Monitor memory usage and key count
Use connection pooling for high-traffic applications
Restrict network access with firewalls
Regular backups for critical cached data

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us