Principle:Langgenius Dify Environment Configuration

Knowledge Sources	Dify
Domains	DevOps, Deployment, Configuration
Last Updated	2026-02-12 00:00 GMT

Overview

Environment Configuration is the principle of externalizing application settings into environment variables so that a single container image can be deployed across different stages without code changes.

Description

Modern containerized applications separate configuration from code by reading runtime parameters from environment variables. In the Dify platform, the docker/.env.example file serves as the canonical template containing every tunable parameter for the entire stack: API service, worker, web frontend, database, cache, vector store, sandbox, plugin daemon, and reverse proxy. Operators copy this template to a .env file and customize values for their specific deployment environment.

This principle solves several problems:

• Security isolation -- Secrets such as SECRET_KEY, DB_PASSWORD, and REDIS_PASSWORD are kept outside version control when the .env file is excluded from commits.
• Environment parity -- The same Docker images run in development, staging, and production; only the .env values differ.
• Single source of truth -- All services in the docker-compose.yaml reference the same .env file through variable interpolation (e.g., ${DB_PASSWORD:-difyai123456}), preventing configuration drift between services.
• Safe defaults -- Every variable carries a sensible default via the ${VAR:-default} syntax, so a fresh deployment works out-of-the-box while still allowing full customization.

Key parameter categories include:

• Application secrets -- SECRET_KEY, PLUGIN_DAEMON_KEY, PLUGIN_DIFY_INNER_API_KEY
• Database credentials -- DB_USERNAME, DB_PASSWORD, DB_HOST, DB_PORT, DB_DATABASE
• Cache credentials -- REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
• Vector store selection -- VECTOR_STORE (default: weaviate)
• Service tuning -- SERVER_WORKER_AMOUNT, GUNICORN_TIMEOUT, CELERY_WORKER_AMOUNT

Usage

Use this principle whenever:

• Setting up a new Dify deployment from scratch.
• Rotating secrets or credentials for an existing deployment.
• Migrating a deployment between hosts or cloud providers.
• Upgrading Dify to a new version that introduces new environment variables.

Theoretical Basis

The Twelve-Factor App methodology (Factor III: Config) prescribes storing configuration in the environment. Dify implements this by maintaining a single .env.example template that enumerates every configurable parameter along with inline documentation:

# Pseudocode: Environment configuration flow
1. Operator copies .env.example -> .env
2. Operator edits .env with deployment-specific values
3. docker compose reads .env and interpolates variables
4. Each service container receives its relevant subset of env vars
5. Application code reads os.environ / process.env at startup

The x-shared-env YAML anchor in docker-compose.yaml consolidates variables shared between the API and worker services, ensuring they always read identical configuration. Services that need only a subset (e.g., the web service) declare their own, smaller environment block.

Default values follow the pattern ${VARIABLE:-fallback}, which allows Docker Compose to substitute the fallback when the variable is unset. This guarantees a functional deployment even without a .env file, though production use should always provide explicit values for secrets.

Related Pages

• Implementation:Langgenius_Dify_Env_File_Setup