How to Configure the Storage System in LunaTV: Kvrocks, Redis, and Upstash Setup

LunaTV selects its storage backend at runtime via the STORAGE environment variable, instantiating Kvrocks, Upstash Redis, or local Redis drivers without requiring code changes.

LunaTV implements a pluggable storage architecture that abstracts persistence behind a unified interface. The system dynamically loads the appropriate driver based on environment configuration, allowing seamless switching between self-hosted Kvrocks, managed Upstash Redis, or local Redis instances. This design centers around the factory pattern in src/lib/db.ts and strict configuration validation in src/lib/config.ts.

Supported Storage Backends

LunaTV provides three distinct storage implementations, each optimized for specific infrastructure requirements.

Kvrocks (Persistent KV Store)

Kvrocks provides a Redis-compatible persistent storage layer ideal for self-hosted deployments requiring data durability. The implementation in src/lib/kvrocks.db.ts extends BaseRedisStorage to communicate with Kvrocks endpoints using standard Redis protocol semantics while persisting data to disk.

Upstash (Serverless Redis)

Upstash offers a fully managed, serverless Redis API accessible via HTTP REST. The driver in src/lib/upstash.db.ts wraps Upstash's REST interface, making it optimal for serverless deployments where maintaining persistent TCP connections is problematic or impossible.

Redis (Local Development)

Redis via the standard client in src/lib/redis.db.ts serves local development and traditional containerized deployments. This implementation uses the standard Node.js Redis client with full command compatibility for testing environments that require native Redis protocol support.

Configuration Environment Variables

The src/lib/config.ts module parses environment variables to determine storage selection and connection parameters. Configure these variables in your .env file or deployment environment:

• STORAGE: Defines the backend type. Accepts "kvrocks", "upstash", or "redis".
• KVROCKS_URL: Connection URI for Kvrocks instances (e.g., redis://user:pass@host:6379).
• UPSTASH_REDIS_REST_URL: HTTPS endpoint for Upstash Redis REST API.
• UPSTASH_REDIS_REST_TOKEN: Authentication token for Upstash REST requests.
• REDIS_URL: Standard Redis connection URI for local or custom deployments.
• REDIS_PASSWORD: Optional authentication credential when using the Redis backend.

How the Storage Factory Works

The createStorage() function in src/lib/db.ts acts as the central factory that instantiates the appropriate driver. This function reads configuration via getConfig() and returns a storage implementation matching the STORAGE environment variable.

// src/lib/db.ts
import { KvrocksStorage } from './kvrocks.db';
import { UpstashStorage } from './upstash.db';
import { RedisStorage } from './redis.db';
import { getConfig } from './config';

export function createStorage() {
  const cfg = getConfig();
  switch (cfg.storage) {
    case 'kvrocks':  return new KvrocksStorage();
    case 'upstash': return new UpstashStorage();
    case 'redis':   return new RedisStorage();
    default:        throw new Error('Unsupported storage type');
  }
}

The factory throws an explicit error if STORAGE is undefined or contains an unsupported value, preventing the application from starting with an invalid configuration.

Step-by-Step Configuration Examples

Configuring Kvrocks

To use Kvrocks as your persistence layer, set the following environment variables:

# .env

STORAGE=kvrocks
KVROCKS_URL=redis://user:password@kvrocks.example.com:6379

The KvrocksStorage class handles connection pooling and protocol compatibility automatically. Once configured, use the storage interface:

import { createStorage } from '@/lib/db';

const storage = createStorage();
await storage.set('user:1234:token', 'abcdef');
const token = await storage.get('user:1234:token');

Configuring Upstash

For serverless deployments using Upstash Redis, configure these variables:

# .env

STORAGE=upstash
UPSTASH_REDIS_REST_URL=https://example.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxxxxxxxxxxxxxxxxxxx

The UpstashStorage implementation translates standard Redis commands into HTTP requests to Upstash's REST API, handling authentication and retry logic internally.

Configuring Local Redis

For development environments, point LunaTV to a local Redis instance:

# .env

STORAGE=redis
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=optional_dev_password

This configuration instantiates the RedisStorage class from src/lib/redis.db.ts, which uses the standard Node.js Redis client for maximum compatibility with local development tools.

Validation and Error Handling

The src/lib/config.ts module validates required environment variables during application startup. If you select STORAGE=kvrocks but omit KVROCKS_URL, the configuration loader throws an initialization error before the storage factory attempts connection. This early validation prevents runtime failures in production environments.

Similarly, selecting upstash without both UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN results in a descriptive error indicating exactly which variables are missing.

Summary

• LunaTV abstracts storage behind a unified interface implemented in src/lib/db.ts.
• Three backends are supported: Kvrocks (kvrocks.db.ts), Upstash (upstash.db.ts), and Redis (redis.db.ts).
• The STORAGE environment variable controls backend selection without code changes.
• Configuration validation occurs in src/lib/config.ts before application startup.
• Each backend requires specific environment variables: KVROCKS_URL, UPSTASH_REDIS_REST_URL/TOKEN, or REDIS_URL.

Frequently Asked Questions

What storage backends does LunaTV support?

LunaTV supports Kvrocks for persistent self-hosted storage, Upstash for serverless Redis via REST API, and standard Redis for local development. Each implementation resides in src/lib/kvrocks.db.ts, src/lib/upstash.db.ts, and src/lib/redis.db.ts respectively.

How do I switch between storage backends in LunaTV?

Change the STORAGE environment variable to "kvrocks", "upstash", or "redis" and provide the corresponding connection URLs. The createStorage() factory in src/lib/db.ts automatically instantiates the correct driver on the next application restart. No code modifications are required.

Is Kvrocks compatible with standard Redis clients?

Yes. The Kvrocks implementation in src/lib/kvrocks.db.ts extends BaseRedisStorage and uses Redis protocol compatibility. You can use standard Redis connection URLs and commands, though Kvrocks persists data to disk rather than memory.

Can I use authentication with the Redis backend?

Yes. Set REDIS_PASSWORD in your environment variables when using the Redis backend. The RedisStorage class passes this credential to the underlying Redis client. For Kvrocks, embed credentials directly in the KVROCKS_URL using standard Redis URI syntax (redis://user:pass@host:port).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}