# Environment Variables Needed to Deploy Folia: Complete Configuration Guide

> Deploy Folia easily by understanding required environment variables like VITE_NETEASE_API_BASE and VITE_AI_PROVIDER. Get Gemini or OpenAI API keys and configuration details for a successful setup.

- Repository: [冬霧/folia-major](https://github.com/chthollyphile/folia-major)
- Tags: how-to-guide
- Published: 2026-07-06

---

**To deploy Folia, you must configure `VITE_NETEASE_API_BASE` for music metadata, set `VITE_AI_PROVIDER` to choose between Google Gemini or OpenAI-compatible services, and supply the corresponding API credentials (`GEMINI_API_KEY` for Google, or `OPENAI_API_KEY`, `OPENAI_API_URL`, and `OPENAI_API_MODEL` for OpenAI), along with an optional `APP_VERSION_LABEL` for build identification.**

The open-source **Folia** project ([chthollyphile/folia-major](https://github.com/chthollyphile/folia-major)) relies on environment variables to connect with external APIs. These variables enable the application to retrieve lyrics from Netease Cloud Music and generate visual themes using AI models, with values injected at build time by Vite and accessed at runtime by the Electron main process.

## Required Environment Variables

Folia requires specific variables to configure its Netease Cloud Music integration and AI theme generation capabilities. All variables are documented in the repository’s `.env.example` file and referenced throughout the source code.

### Netease Cloud Music API Configuration

**`VITE_NETEASE_API_BASE`** defines the base URL for the Netease Cloud Music API. The frontend uses this endpoint in [`src/services/netease.ts`](https://github.com/chthollyphile/folia-major/blob/main/src/services/netease.ts) to fetch lyrics and track metadata.

```bash
VITE_NETEASE_API_BASE=https://netease.example.com

```

### AI Provider Selection

**`VITE_AI_PROVIDER`** determines which AI backend handles theme generation. According to the source code in [`src/utils/aiThemePrompts.ts`](https://github.com/chthollyphile/folia-major/blob/main/src/utils/aiThemePrompts.ts), this variable accepts exactly two values:

- **`google`** – Uses Google Gemini for theme generation
- **`openai`** – Uses any OpenAI-compatible API (including OpenAI, DeepSeek, or Qwen)

```bash
VITE_AI_PROVIDER=google

```

### Google Gemini Configuration

When `VITE_AI_PROVIDER` is set to `google`, you must provide **`GEMINI_API_KEY`**. This key is read at runtime in [`api/generate-theme.ts`](https://github.com/chthollyphile/folia-major/blob/main/api/generate-theme.ts) and injected into the build via [`vite.config.ts`](https://github.com/chthollyphile/folia-major/blob/main/vite.config.ts):

```typescript
// vite.config.ts (excerpt)
define: {
  'process.env.GEMINI_API_KEY': JSON.stringify(env.GEMINI_API_KEY),
}

```

```bash
GEMINI_API_KEY=sk-your-gemini-key-here

```

### OpenAI-Compatible Service Configuration

When `VITE_AI_PROVIDER` is set to `openai`, you must configure three variables read by [`api/generate-theme_openai.ts`](https://github.com/chthollyphile/folia-major/blob/main/api/generate-theme_openai.ts):

- **`OPENAI_API_KEY`** – Authentication key for the service
- **`OPENAI_API_URL`** – Base URL for the API endpoint (e.g., `https://api.openai.com/v1`)
- **`OPENAI_API_MODEL`** – Model identifier (e.g., `gpt-4o`)

```typescript
// api/generate-theme_openai.ts (excerpt)
const apiKey = process.env.OPENAI_API_KEY;
const apiUrl = normalizeOpenAIChatCompletionsUrl(process.env.OPENAI_API_URL);
const model = resolveOpenAICompatibleModel(apiUrl, process.env.OPENAI_API_MODEL);

```

```bash
OPENAI_API_KEY=sk-your-openai-key-here
OPENAI_API_URL=https://api.openai.com/v1
OPENAI_API_MODEL=gpt-4o

```

### Optional Build Metadata

**`APP_VERSION_LABEL`** is an optional variable that specifies a human-readable version label shown in the UI. If omitted, the default value `folia-major` is used. According to the source, this is injected at line 185 in [`vite.config.ts`](https://github.com/chthollyphile/folia-major/blob/main/vite.config.ts) and accessed by the Electron main process via `process.env.APP_VERSION_LABEL`.

```bash
APP_VERSION_LABEL=folia-v2.3.0

```

## How Variables Are Injected

Folia uses Vite’s `define` configuration to inject environment variables at build time. This makes them available as `process.env` properties within the application code. The Electron main process reads these values at runtime to initialize connections to external services.

Key files handling environment configuration:

- **`.env.example`** – Template showing all required and optional variables
- **[`vite.config.ts`](https://github.com/chthollyphile/folia-major/blob/main/vite.config.ts)** – Build-time injection logic and `APP_VERSION_LABEL` handling
- **[`api/generate-theme.ts`](https://github.com/chthollyphile/folia-major/blob/main/api/generate-theme.ts)** – Runtime usage of `GEMINI_API_KEY`
- **[`api/generate-theme_openai.ts`](https://github.com/chthollyphile/folia-major/blob/main/api/generate-theme_openai.ts)** – Runtime usage of `OPENAI_*` variables
- **[`src/services/netease.ts`](https://github.com/chthollyphile/folia-major/blob/main/src/services/netease.ts)** – Frontend usage of `VITE_NETEASE_API_BASE`

## Complete Configuration Example

Create a `.env` file in the project root with the following structure:

```bash

# Netease Cloud Music API

VITE_NETEASE_API_BASE=https://netease.example.com

# AI Provider Selection (google or openai)

VITE_AI_PROVIDER=google

# For Google Gemini:

GEMINI_API_KEY=sk-your-gemini-key-here

# For OpenAI-compatible services (uncomment if using openai):

# OPENAI_API_KEY=sk-your-openai-key-here

# OPENAI_API_URL=https://api.openai.com/v1

# OPENAI_API_MODEL=gpt-4o

# Optional version label

APP_VERSION_LABEL=folia-v2.3.0

```

## Summary

- **`VITE_NETEASE_API_BASE`** is required to fetch lyrics and metadata from Netease Cloud Music
- **`VITE_AI_PROVIDER`** must be set to either `google` or `openai` to enable theme generation
- **`GEMINI_API_KEY`** is required only when using Google Gemini as the AI provider
- **`OPENAI_API_KEY`**, **`OPENAI_API_URL`**, and **`OPENAI_API_MODEL`** are required only when using OpenAI-compatible services
- **`APP_VERSION_LABEL`** is optional and defaults to `folia-major` if not specified
- All variables are defined in `.env.example` and injected via [`vite.config.ts`](https://github.com/chthollyphile/folia-major/blob/main/vite.config.ts) using Vite’s `define` configuration

## Frequently Asked Questions

### What happens if I don't set VITE_AI_PROVIDER?

Folia will not be able to generate AI-powered themes. The application requires this variable to determine which backend service to call in [`src/utils/aiThemePrompts.ts`](https://github.com/chthollyphile/folia-major/blob/main/src/utils/aiThemePrompts.ts), and theme generation functionality will fail without it.

### Can I use custom OpenAI-compatible endpoints like DeepSeek or Qwen?

Yes. Set `VITE_AI_PROVIDER=openai` and configure `OPENAI_API_URL` to point to your custom endpoint (e.g., `https://api.deepseek.com/v1` or `https://dashscope.aliyuncs.com/v1`). The `OPENAI_API_MODEL` should contain the specific model name supported by that provider.

### Where should I store these variables in production?

Store sensitive API keys in environment variables on your deployment server or CI/CD pipeline, never in the source code. The `.env` file should be added to `.gitignore` to prevent accidental commits, as demonstrated in the repository’s `.env.example` file structure.

### Is APP_VERSION_LABEL required for the application to function?

No. This variable is optional. If omitted, the application defaults to using `folia-major` as the version label, which is injected at build time in [`vite.config.ts`](https://github.com/chthollyphile/folia-major/blob/main/vite.config.ts) (line 185) and displayed in the application interface.