# What Is Kvrocks and Why It’s Recommended for Self-Hosted LunaTV Deployments > Discover Kvrocks, a Redis-compatible key-value store ideal for self-hosted LunaTV. Prevent data loss with built-in disk persistence during container restarts. Zero code changes needed. - Repository: [MoonTechLab/LunaTV](https://github.com/MoonTechLab/LunaTV) - Tags: deep-dive - Published: 2026-09-08 --- **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`](https://github.com/MoonTechLab/LunaTV/blob/main/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: ```typescript // 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`](https://github.com/MoonTechLab/LunaTV/blob/main/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: ```typescript // 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: ```yaml # 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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/kvrocks.db.ts), which extends `BaseRedisStorage` and connects via the `KVROCKS_URL` environment variable. - The storage factory in [`src/lib/db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/db.ts), Kvrocks specifically targets Docker-based or bare-metal deployments where local disk persistence is preferred over managed cloud services.