Principle:Langgenius Dify Deployment Upgrade

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

Overview

Deployment Upgrade is the principle of safely updating a running Dify installation by synchronizing environment configuration with the latest template and applying database schema migrations, while preserving operator customizations and creating rollback points.

Description

Upgrading a Dify deployment involves two coordinated activities:

1. Environment variable synchronization -- New Dify versions frequently introduce new environment variables or change defaults. The dify-env-sync.sh script merges the updated .env.example into the existing .env, adding new variables while preserving operator-customized values.
2. Database schema migration -- Flask-Migrate (Alembic) applies incremental DDL changes to the PostgreSQL or MySQL schema. The create_migrations_app() factory function creates a lightweight Flask app with only the database and migration extensions initialized.

This principle ensures:

• Zero data loss -- Custom environment values (secrets, credentials, tuned parameters) are never overwritten during the sync.
• Rollback capability -- A timestamped backup of the .env file is created before any changes, stored in the env-backup/ directory.
• Visibility -- The script reports which variables differ, which are new, and which have been removed from the upstream template.
• Automatic migration -- When MIGRATION_ENABLED=true (the default), the API container automatically runs flask db upgrade at startup, applying any pending Alembic revisions.
• Minimal downtime -- The migration app (create_migrations_app) initializes only ext_database and ext_migrate, avoiding the overhead of starting Celery, Redis connections, or other extensions.

The upgrade workflow follows this sequence:

1. Pull the latest Docker images (docker compose pull).
2. Run dify-env-sync.sh to merge new environment variables.
3. Run docker compose up -d to restart services with updated images.
4. The API container detects pending migrations and applies them automatically.

Usage

Use this principle when:

• Upgrading Dify to a new release version.
• Adding newly introduced environment variables after a version bump.
• Understanding how database schema changes are applied automatically.
• Rolling back a failed upgrade using the environment backup.

Theoretical Basis

The upgrade process follows a two-phase configuration management approach: static configuration (environment variables) and dynamic schema (database DDL).

Pseudocode: Complete upgrade workflow

Phase 1 -- Environment Sync (dify-env-sync.sh):
    main():
        1. check_files()
           - Verify .env.example exists
           - Create .env from template if missing
        2. create_backup()
           - mkdir -p env-backup/
           - cp .env env-backup/.env.backup_YYYYMMDD_HHMMSS
        3. detect_differences()
           - Compare .env vs .env.example using AWK
           - Report changed values with analysis (numeric, boolean, URL, etc.)
        4. detect_removed_variables()
           - Find variables in .env not present in .env.example
           - Warn operator to manually review removals
        5. sync_env_file()
           - Rebuild .env from .env.example structure
           - Preserve custom values, add new variables with defaults
        6. show_statistics()
           - Display total env var counts

Phase 2 -- Database Migration (automatic at container startup):
    create_migrations_app():
        1. create_flask_app_with_configs()  -- load env vars
        2. ext_database.init_app(app)       -- connect to DB
        3. ext_migrate.init_app(app)        -- initialize Alembic
        4. flask db upgrade                 -- apply pending revisions

The environment sync script uses AWK for performance optimization when processing the large .env.example file (600+ variables). It creates a lookup table of preserved values and rebuilds the file in a single pass, maintaining the original comment structure and section organization from the template.

The backup strategy is append-only: each sync creates a new timestamped backup file rather than overwriting the previous one, providing a full history of configuration changes over time.

Related Pages

• Implementation:Langgenius_Dify_Env_Sync_Script