What Is Kvrocks and Why It’s Recommended for Self-Hosted LunaTV Deployments

Kvrocks is a Redis-compatible key-value store that adds built-in disk persistence to the Redis protocol, making it the recommended storage backend for LunaTV self-hosted deployments because it prevents data loss during container restarts while requiring zero code changes.

LunaTV is an open-source streaming platform that stores user-specific data—playback history, favorites, and sync information—that must survive server restarts. While pure Redis keeps data only in memory, Kvrocks writes data to disk by default, providing the durability required for production self-hosted environments without breaking the existing Redis-based architecture.

What Is Kvrocks?

Kvrocks is an open-source storage engine developed by Apache that implements the Redis protocol while storing data on disk rather than in memory. By default, it persists data to /var/lib/kvrocks/db, ensuring that key-value pairs survive container restarts, host crashes, or power failures.

Unlike standard Redis, which requires explicit RDB snapshots or AOF configuration for persistence, Kvrocks treats disk storage as the primary mechanism. This makes it a drop-in replacement for Redis in applications that need durability without complex configuration.

How LunaTV Implements Kvrocks Storage

The LunaTV codebase treats Kvrocks as a first-class storage option through a dedicated driver architecture that extends the existing Redis infrastructure.

The Storage Driver Class

In src/lib/kvrocks.db.ts, the KvrocksStorage class extends BaseRedisStorage to implement the storage driver. It injects the connection URL from environment variables and maintains a global client singleton to prevent connection leaks:

// src/lib/kvrocks.db.ts – driver implementation
import { BaseRedisStorage } from './redis-base.db';

export class KvrocksStorage extends BaseRedisStorage {
  constructor() {
    const config = {
      url: process.env.KVROCKS_URL!,   // e.g. redis://moontv-kvrocks:6666
      clientName: 'Kvrocks'
    };
    const globalSymbol = Symbol.for('__MOONTV_KVROCKS_CLIENT__');
    super(config, globalSymbol);
  }
}

Environment Configuration

LunaTV selects the storage backend through environment variables defined in the deployment configuration. Set NEXT_PUBLIC_STORAGE_TYPE to kvrocks and provide the connection string via KVROCKS_URL:

• NEXT_PUBLIC_STORAGE_TYPE=kvrocks
• KVROCKS_URL=redis://moontv-kvrocks:6666

Storage Factory Selection

The factory function in src/lib/db.ts instantiates the appropriate storage driver based on the NEXT_PUBLIC_STORAGE_TYPE value. When set to 'kvrocks', it returns a new KvrocksStorage instance:

// src/lib/db.ts – storage selection
export function createStorage() {
  const type = process.env.NEXT_PUBLIC_STORAGE_TYPE;
  switch (type) {
    case 'kvrocks':
      return new KvrocksStorage();
    case 'redis':
      return new RedisStorage();
    case 'upstash':
      return new UpstashStorage();
    default:
      throw new Error('Unsupported storage type');
  }
}

Why Kvrocks Is the Recommended Choice for Self-Hosting

According to the MoonTechLab/LunaTV source code and deployment documentation, Kvrocks is the recommended storage solution for self-hosted deployments for four critical reasons:

Persistent data by default. Unlike plain Redis, which stores data only in memory unless explicitly configured with RDB or AOF, Kvrocks automatically writes data to disk. This prevents loss of playback records, user favorites, and viewing history after container restarts or host crashes.

Docker-friendly architecture. The official apache/kvrocks image requires only a simple volume mapping to maintain data outside the container. Mapping kvrocks-data:/var/lib/kvrocks ensures database files persist across container recreations.

Zero-code migration. Because Kvrocks implements the Redis protocol, the existing LunaTV codebase—which communicates via Redis-like clients—works without modification. The only required change is updating the NEXT_PUBLIC_STORAGE_TYPE environment variable.

One-click deployment support. Zeabur’s one-click LunaTV template automatically provisions a Kvrocks service alongside the application, providing users with a ready-to-run, durable backend out of the box.

Self-Hosted Deployment Example

To deploy LunaTV with Kvrocks using Docker Compose, configure the moontv-kvrocks service with a persistent volume and reference it from the core application:

# docker-compose.yml – recommended self-hosted setup

services:
  moontv-core:
    image: ghcr.io/moontechlab/lunatv:latest
    environment:
      - NEXT_PUBLIC_STORAGE_TYPE=kvrocks
      - KVROCKS_URL=redis://moontv-kvrocks:6666
    depends_on:
      - moontv-kvrocks
  moontv-kvrocks:
    image: apache/kvrocks
    volumes:
      - kvrocks-data:/var/lib/kvrocks
volumes:
  kvrocks-data:

This configuration ensures that user data written to the KvrocksStorage driver persists in the kvrocks-data volume, surviving container restarts and updates.

Summary

• Kvrocks is an Apache open-source key-value store that adds disk persistence to the Redis protocol, storing data in /var/lib/kvrocks/db by default.
• LunaTV implements Kvrocks support through the KvrocksStorage class in src/lib/kvrocks.db.ts, which extends BaseRedisStorage and connects via the KVROCKS_URL environment variable.
• The storage factory in src/lib/db.ts selects the Kvrocks driver when NEXT_PUBLIC_STORAGE_TYPE is set to 'kvrocks'.
• Kvrocks is recommended for self-hosted deployments because it provides automatic persistence, simple Docker volume management, protocol compatibility with existing Redis code, and support for one-click deployment templates.

Frequently Asked Questions

What is the difference between Kvrocks and Redis for LunaTV deployments?

Kvrocks implements the same Redis protocol but stores data on disk by default, whereas standard Redis stores data only in memory unless explicitly configured with persistence files. For LunaTV, this means user playback history and favorites survive container restarts when using Kvrocks, but may be lost with default Redis configurations.

Can I switch from Redis to Kvrocks without losing data?

Switching storage backends requires migrating data between stores, as LunaTV’s storage selector in src/lib/db.ts instantiates only one driver at a time. However, because both use the Redis protocol, you can use standard Redis replication tools or export/import scripts to transfer data before changing the NEXT_PUBLIC_STORAGE_TYPE environment variable.

Where does Kvrocks store data in a Docker deployment?

In the official apache/kvrocks Docker image, data is stored in /var/lib/kvrocks by default. The recommended LunaTV compose configuration mounts a persistent volume to this path (kvrocks-data:/var/lib/kvrocks), ensuring database files remain on the host filesystem even if the container is removed or recreated.

Is Kvrocks compatible with managed Redis services like Upstash?

Kvrocks is designed for self-hosted scenarios where you control the storage layer. While LunaTV supports Upstash via a separate UpstashStorage driver in src/lib/db.ts, Kvrocks specifically targets Docker-based or bare-metal deployments where local disk persistence is preferred over managed cloud services.

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