Environment Variables Needed to Deploy Folia: Complete Configuration Guide

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) 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 to fetch lyrics and track metadata.

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, this variable accepts exactly two values:

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

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 and injected into the build via vite.config.ts:

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

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:

• 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)

// 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);

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 and accessed by the Electron main process via process.env.APP_VERSION_LABEL.

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 – Build-time injection logic and APP_VERSION_LABEL handling
• api/generate-theme.ts – Runtime usage of GEMINI_API_KEY
• api/generate-theme_openai.ts – Runtime usage of OPENAI_* variables
• 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:

# 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 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, 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 (line 185) and displayed in the application interface.

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