Heuristic:Langgenius Dify Env Sync Upgrade Strategy
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Operations |
| Last Updated | 2026-02-08 11:00 GMT |
Overview
Safe environment variable synchronization strategy during Dify version upgrades using `dify-env-sync.sh` to add new variables from `.env.example` while preserving all existing custom configurations.
Description
When Dify releases a new version, new environment variables are often added to `.env.example`. Manually diffing and merging these changes into the existing `.env` file is error-prone and can lead to missing critical configuration. The `dify-env-sync.sh` script automates this process using AWK-based one-way synchronization: it adds newly introduced variables from the template while never overwriting user-customized values. It also detects deprecated (removed) variables for manual review.
Usage
Apply this heuristic every time you upgrade Dify to a new version. Run `./dify-env-sync.sh` in the `docker/` directory after pulling new code but before running `docker compose up -d`. This is critical for the Dify_Env_Sync implementation.
The Insight (Rule of Thumb)
- Action: Always run `./dify-env-sync.sh` after git pull and before `docker compose up -d` during upgrades.
- Value: Automatically adds 0-50+ new environment variables per release while preserving custom values.
- Trade-off: Removes no deprecated variables automatically; manual review required for removed vars.
- Safety net: Timestamped backups are created in `env-backup/` directory before any changes.
Reasoning
Dify's `.env.example` file contains 500+ environment variables across dozens of categories. Manual merging during upgrades is guaranteed to miss new variables, potentially leaving the system in a broken state (missing Redis passwords, wrong sandbox keys, etc.). The AWK-based script handles large files efficiently and provides clear output about what was added vs. what was preserved.
The script follows a conservative strategy: it only ADDS new variables and NEVER modifies existing ones. This means if a default value changes between versions, the old value is preserved (which may or may not be desired). The operator should review the script output for any warnings about changed defaults.
Code Evidence
Backup creation from `docker/dify-env-sync.sh:85-98`:
# Create timestamped backup before any changes
BACKUP_DIR="env-backup"
mkdir -p "$BACKUP_DIR"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp .env "$BACKUP_DIR/.env.backup.$TIMESTAMP"
AWK-based comparison from `docker/dify-env-sync.sh:116-143`:
# Efficient AWK-based comparison for large .env files
awk -F'=' 'NR==FNR { existing[$1]; next }
!($1 in existing) { print $0 }
' .env .env.example >> .env