Implementation:Langgenius Dify Dify Env Sync
| Knowledge Sources | |
|---|---|
| Domains | DevOps Configuration Management Upgrade Management |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
The dify-env-sync.sh script synchronizes an operator's .env file with the latest .env.example template, preserving custom values while adding new variables, detecting removed variables, and creating timestamped backups.
Description
Located at docker/dify-env-sync.sh (465 lines), this Bash script automates the configuration synchronization workflow during Dify upgrades. It is designed for large environment files (~300 variables) and uses AWK-based processing for performance.
The script is organized into the following key functions:
handle_error(line_no, error_code) (Lines 20-26): An error trap handler registered via trap 'handle_error ${LINENO} $?' ERR. When any command fails (due to set -eo pipefail), this function prints the error location and exits with the original error code.
check_files() (Lines 65-80): Verifies that .env.example exists (aborting if not found) and creates .env from the template if it does not yet exist. This handles the first-time setup case.
create_backup() (Lines 84-99): Creates a timestamped backup of the current .env file into the env-backup/ directory. The backup filename follows the pattern .env.backup_YYYYMMDD_HHMMSS. Creates the backup directory if it does not exist.
detect_differences() (Lines 101-152): Uses an AWK script to efficiently compare key-value pairs between .env and .env.example. It skips comment lines and blank lines, extracts keys and values from both files, and records pairs where the same key has different values. The differences are written to a temporary file using \x01 (SOH) as the field separator to avoid conflicts with variable values.
parse_env_line(line) (Lines 161-185): A utility function that parses a single environment variable line, extracting the key and value using regex matching. Returns the result in key|value format. Handles edge cases like leading/trailing whitespace and lines without an equals sign.
show_differences_detail() (Lines 188-216): Reads the difference file and displays each changed variable with its current .env value and the recommended .env.example value, using color-coded output for readability.
analyze_value_change(current_value, recommended_value) (Lines 219-262): Classifies the type of value change for better operator understanding:
- Empty-to-value or value-to-empty transitions
- Numeric increases or decreases (using arithmetic evaluation with
10#prefix for leading zeros) - Boolean value changes
- URL/endpoint changes
- File path changes
- String length differences
sync_env_file() (Lines 267-376): The core synchronization function. Uses AWK to process .env.example line by line, substituting preserved custom values from .env while keeping the template structure (comments, ordering, new variables). The result is written to .env.new and then atomically moved to .env. Reports counts of preserved and updated values.
detect_removed_variables() (Lines 379-421): Identifies variables present in .env but absent from .env.example using the comm command on sorted key lists. Reports these as warnings, suggesting manual removal.
show_statistics() (Lines 424-432): Displays final counts of environment variables in both files.
main() (Lines 436-459): The orchestration function that executes all phases in order: check_files, create_backup, detect_differences, detect_removed_variables, sync_env_file, show_statistics.
The script uses set -eo pipefail for strict error handling and only executes main when run directly (not when sourced), enabling unit testing of individual functions.
Usage
Run this script from the docker/ directory after pulling a new Dify release. It should be executed before docker compose up -d to ensure the .env file is synchronized with the latest template.
Code Reference
Source Location
- Repository: Dify
- File:
docker/dify-env-sync.sh(Lines 1-465)
Signature
#!/bin/bash
# Main functions:
handle_error(line_no, error_code) # Error trap handler (L20-26)
check_files() # Verify prerequisites (L65-80)
create_backup() # Timestamped backup (L84-99)
detect_differences() # AWK-based diff detection (L101-152)
parse_env_line(line) # Parse key=value lines (L161-185)
show_differences_detail() # Display color-coded diffs (L188-216)
analyze_value_change(current, rec) # Classify change types (L219-262)
sync_env_file() # Core merge operation (L267-376)
detect_removed_variables() # Find deprecated vars (L379-421)
show_statistics() # Report variable counts (L424-432)
main() # Orchestrate all phases (L436-459)
Import
# Direct execution (most common):
bash dify-env-sync.sh
# Or source for testing individual functions:
source dify-env-sync.sh
check_files
create_backup
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
.env |
File (text) | No | The operator's current environment configuration file. If it does not exist, it will be created from .env.example.
|
.env.example |
File (text) | Yes | The latest environment variable template from the Dify release. Must exist or the script aborts with an error. |
Outputs
| Name | Type | Description |
|---|---|---|
Updated .env |
File (text) | The synchronized environment file with the structure of .env.example, new variables from the template, and preserved custom values from the original .env.
|
env-backup/.env.backup_{timestamp} |
File (text) | A timestamped backup of the original .env file taken before any modifications. Format: .env.backup_YYYYMMDD_HHMMSS.
|
| Console output | Colored text | Status messages, difference reports, removed variable warnings, and statistics. Uses ANSI color codes: blue (info), green (success), yellow (warning), red (error). |
Usage Examples
# Standard upgrade workflow
cd dify/docker
git pull origin main
# Run synchronization before restarting services
bash dify-env-sync.sh
# Expected output:
# [INFO] === Dify Environment Variables Synchronization Script ===
# [INFO] Execution started: Sat Feb 8 14:30:22 UTC 2026
# [SUCCESS] Required files verified
# [SUCCESS] Backed up existing .env to env-backup/.env.backup_20260208_143022
# [SUCCESS] Detected differences in 5 environment variables
#
# [1] LOG_LEVEL
# .env (current) : DEBUG
# .env.example (recommended): INFO
# -> String length change (5 -> 4 characters)
#
# [SUCCESS] No removed environment variables found
# [SUCCESS] Partial synchronization of .env file completed
# [INFO] Preserved .env values: 5
# [INFO] Updated to .env.example values: 295
# [SUCCESS] === Synchronization process completed successfully ===
# Restart services with updated configuration
docker compose up -d
# If something goes wrong, restore the backup
cp env-backup/.env.backup_20260208_143022 .env
docker compose up -d