# Complete Guide to Environment Variables for LunaTV Configuration

> Explore LunaTV environment variables for seamless configuration. Learn how to manage settings for authentication, caching, and integrations via process env variables.

- Repository: [MoonTechLab/LunaTV](https://github.com/MoonTechLab/LunaTV)
- Tags: how-to-guide
- Published: 2026-09-09

---

**LunaTV reads all runtime settings via `process.env` variables defined in [`src/lib/config.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts), [`src/middleware.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/middleware.ts), and database client modules to handle authentication, caching, and third-party integrations.**

The [MoonTechLab/LunaTV](https://github.com/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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.

```typescript
// 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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts).
- **ANNOUNCEMENT**: Global banner message displayed on the homepage. Falls back to a default disclaimer regarding third-party content.

```typescript
// 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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts).
- **KVROCKS_URL**: Connection string for KVROCKS compatibility layer, used in [`src/lib/kvrocks.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/upstash.db.ts).

```typescript
// 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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts) | Central configuration object merging all `NEXT_PUBLIC_*` variables and site settings. |
| [`src/middleware.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/middleware.ts) | Validates `NEXT_PUBLIC_STORAGE_TYPE` and admin authentication context. |
| [`src/lib/redis.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts) | Initializes Redis client using `REDIS_URL`. |
| [`src/lib/kvrocks.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/kvrocks.db.ts) | Initializes KVROCKS connection via `KVROCKS_URL`. |
| [`src/lib/upstash.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/app/api/login/route.ts).
- **Client-side storage** is controlled by `NEXT_PUBLIC_STORAGE_TYPE`, defaulting to `localstorage` in [`src/lib/config.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/redis.db.ts) and [`src/lib/upstash.db.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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.