Complete Guide to Environment Variables for LunaTV Configuration

LunaTV reads all runtime settings via process.env variables defined in src/lib/config.ts, src/middleware.ts, and database client modules to handle authentication, caching, and third-party integrations.

The MoonTechLab/LunaTV repository relies on environment variables to customize everything from admin credentials to Redis connection strings. These variables are parsed at runtime through Next.js process.env calls, with a central configuration object defined in src/lib/config.ts (line 204) that provides sensible defaults when variables are omitted.

Core Authentication Variables

LunaTV protects administrative endpoints using simple environment-based credentials. These values are compared directly against incoming requests in API routes such as src/app/api/login/route.ts (line 11) and various src/app/api/admin/*/route.ts files.

• USERNAME: Identifies the site owner and enforces owner-only actions across the API.
• PASSWORD: Optional admin password required for login when set; if omitted, authentication may be bypassed or handled differently depending on route logic.

// src/app/api/login/route.ts pattern
if (authInfo.username !== process.env.USERNAME) {
  throw new Error('Invalid user');
}
if (process.env.PASSWORD && authInfo.password !== process.env.PASSWORD) {
  throw new Error('Invalid password');
}

Frontend Storage and Client-Side Configuration

The application exposes specific variables to the browser using the NEXT_PUBLIC_ prefix, allowing the React frontend to access configuration without exposing server secrets.

• NEXT_PUBLIC_STORAGE_TYPE: Determines client-side storage mechanism. Accepts values like 'localstorage' or 'indexeddb'. Defaults to 'localstorage' when unspecified.
• NEXT_PUBLIC_SITE_NAME: Displayed site title throughout the UI. Defaults to 'MoonTV' as implemented in src/lib/config.ts.
• ANNOUNCEMENT: Global banner message displayed on the homepage. Falls back to a default disclaimer regarding third-party content.

// src/lib/config.ts (line 204)
SiteName: process.env.NEXT_PUBLIC_SITE_NAME || 'MoonTV',

External Caching and Database Connections

LunaTV supports three distinct caching backends selected via environment variables. Each connection is initialized in dedicated database modules under src/lib/.

• REDIS_URL: Connection string for standard Redis, consumed by src/lib/redis.db.ts.
• KVROCKS_URL: Connection string for KVROCKS compatibility layer, used in src/lib/kvrocks.db.ts.
• UPSTASH_URL: HTTPS endpoint for Upstash Redis service, paired with UPSTASH_TOKEN for authentication in src/lib/upstash.db.ts.

// Example: Reading cache configuration
const redisUrl = process.env.REDIS_URL;
const upstashToken = process.env.UPSTASH_TOKEN;

Site Identity and UI Customization

Control visual presentation and behavioral aspects of the LunaTV interface through these public environment variables.

• NEXT_PUBLIC_DISABLE_YELLOW_FILTER: When set to 'true', removes the yellow tint applied to Douban thumbnail images.
• NEXT_PUBLIC_FLUID_SEARCH: Enables continuous search scrolling unless explicitly set to 'false'.
• NEXT_PUBLIC_SEARCH_MAX_PAGE: Limits downstream pagination during searches. Default value is 5.

Search and Third-Party Integrations

LunaTV integrates with Douban for metadata and images, configurable via proxy settings to handle regional restrictions or custom CDN routing.

• NEXT_PUBLIC_DOUBAN_PROXY_TYPE: Specifies the proxy provider for Douban API calls. Default is 'cmliussss-cdn-tencent'.
• NEXT_PUBLIC_DOUBAN_PROXY: Optional custom proxy URL overriding the default provider.
• NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE: Defines the image-proxy provider for thumbnails. Defaults to 'cmliussss-cdn-tencent'.
• NEXT_PUBLIC_DOUBAN_IMAGE_PROXY: Optional custom image-proxy URL for Douban thumbnails.

Configuration File Reference

Environment variables are scattered across specific modules based on their functional domain:

File	Responsibility
src/lib/config.ts	Central configuration object merging all NEXT_PUBLIC_* variables and site settings.
src/middleware.ts	Validates NEXT_PUBLIC_STORAGE_TYPE and admin authentication context.
src/lib/redis.db.ts	Initializes Redis client using REDIS_URL.
src/lib/kvrocks.db.ts	Initializes KVROCKS connection via KVROCKS_URL.
src/lib/upstash.db.ts	Configures Upstash Redis with UPSTASH_URL and UPSTASH_TOKEN.
.env.example	Template file documenting all required variables with placeholder values.

Summary

• Authentication relies on USERNAME and PASSWORD variables checked in API routes like src/app/api/login/route.ts.
• Client-side storage is controlled by NEXT_PUBLIC_STORAGE_TYPE, defaulting to localstorage in src/lib/config.ts.
• Caching backends include Redis, KVROCKS, and Upstash, each configured via distinct URL and token variables.
• Douban integration supports proxy customization through six separate environment variables for API and image requests.
• All variables are accessed via process.env with fallbacks defined in the central configuration module.

Frequently Asked Questions

What are the required environment variables to run LunaTV?

The only strictly required variables are USERNAME and PASSWORD if you intend to use administrative features. However, for a production deployment, you should configure at least one caching backend (REDIS_URL, KVROCKS_URL, or UPSTASH_URL) and set NEXT_PUBLIC_SITE_NAME to customize the branding. The application will run with sensible defaults for storage type and search limits, but caching configuration is essential for performance.

How do I configure Redis or Upstash caching in LunaTV?

Set REDIS_URL to a standard Redis connection string (e.g., redis://localhost:6379) for traditional Redis, or use UPSTASH_URL and UPSTASH_TOKEN for serverless Redis hosting. The application automatically detects these variables in src/lib/redis.db.ts and src/lib/upstash.db.ts respectively. KVROCKS users should populate KVROCKS_URL instead.

Why are some environment variables prefixed with NEXT_PUBLIC_?

Next.js automatically exposes variables prefixed with NEXT_PUBLIC_ to the browser bundle, allowing client-side JavaScript to access configuration values like NEXT_PUBLIC_STORAGE_TYPE and NEXT_PUBLIC_SITE_NAME. Never prefix sensitive values (passwords, tokens, database URLs) with NEXT_PUBLIC_, as this would leak them to users. Keep authentication and connection strings server-side only.

How does LunaTV handle missing environment variables?

The codebase implements fallback values directly in src/lib/config.ts using the logical OR operator. For example, process.env.NEXT_PUBLIC_SITE_NAME || 'MoonTV' ensures the site displays "MoonTV" when the variable is undefined. Authentication variables have no defaults and must be explicitly set to enable admin functionality, while caching modules will fail gracefully or skip initialization if their respective URLs are missing.

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