Why “Image Tag Update Only” Is Risky #

With large version gaps, Dify may not be able to absorb a simple container image update alone. When comparing the actual differences, this update had the following key points.

Upgrade Strategy for This Update #

1. First, take a full backup including docker/volumes
2. Obtain official v1.13.3 in a separate directory to establish a diff baseline
3. Replace docker-compose.yaml with the official version
4. Restore only environment-specific settings like .env and TLS mounts
5. Update Sandbox configuration files to match new assumptions
6. Validate syntax with docker compose config before startup
7. After startup, verify not just the UI but also Knowledge / Plugin / Code execution

1. Take a Backup First #

The most important thing is to ensure you can revert to the pre-update compose and volumes. Especially with Weaviate or PostgreSQL, there are definitely scenarios where you might want to rollback after an update.

cd /srv/dify/docker
TS=$(date +%Y%m%d%H%M%S)

cp -a docker-compose.yaml "docker-compose.yaml.${TS}.bak"
cp -a .env ".env.${TS}.bak"
[ -f volumes/sandbox/conf/config.yaml ] && \
  cp -a volumes/sandbox/conf/config.yaml "volumes/sandbox/conf/config.yaml.${TS}.bak"

tar -czf "/root/dify-volumes-${TS}.tgz" volumes

The paths shown here are examples for public release. In production, adapt them to your own environment’s directory structure.

2. Obtain Official v1.13.3 #

Instead of directly modifying the existing directory, fetch it to a separate directory for comparison. The key point is not overwriting existing environment files at this stage.

cd /tmp
rm -rf dify-1.13.3
git clone --branch 1.13.3 https://github.com/langgenius/dify.git dify-1.13.3

After fetching, comparing at least three files makes it easier to understand what needs to be absorbed in this update: docker-compose.yaml, .env.example, and volumes/sandbox/conf/config.yaml.example.

3. Replace Compose with Official Version #

This time, rather than continuing to modify the existing compose, we adopted the official v1.13.3 directly as the foundation. This makes future upgrades easier to track “differences from official.”

cp /tmp/dify-1.13.3/docker/docker-compose.yaml /srv/dify/docker/docker-compose.yaml
cp /tmp/dify-1.13.3/docker/.env.example /srv/dify/docker/.env.example.1.13.3
cp /tmp/dify-1.13.3/docker/volumes/sandbox/conf/config.yaml.example \
   /srv/dify/docker/volumes/sandbox/conf/config.yaml.example.1.13.3

4. Restore Environment-Specific Settings #

After adopting the official compose, restore only the settings needed for production operations as an overlay. In our environment, the following items were particularly important.

DB_TYPE=postgresql
DB_HOST=db_postgres
DB_PORT=5432

VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_GRPC_ENDPOINT=grpc://weaviate:50051
WEAVIATE_API_KEY=<YOUR_WEAVIATE_API_KEY>

NGINX_SERVER_NAME=<YOUR_DOMAIN>
NGINX_HTTPS_ENABLED=true
NGINX_SSL_CERT_FILENAME=live/<YOUR_DOMAIN>/fullchain.pem
NGINX_SSL_CERT_KEY_FILENAME=live/<YOUR_DOMAIN>/privkey.pem

FILES_URL=https://<YOUR_DOMAIN>
INTERNAL_FILES_URL=http://api:5001
PLUGIN_MAX_EXECUTION_TIMEOUT=1800

The key point is to not carry over all old environment variables, but rather reconfigure only needed items based on the new official .env.example. Particularly DB_HOST and Weaviate-related settings are areas prone to causing errors after startup if reused from the old compose.

5. Restore NGINX Certificate Mounts #

After replacing with the official compose, TLS mount configuration may diverge from your environment’s assumptions. This time, we managed certificates in an existing host directory, so we readjusted mounts only for the NGINX service.

services:
  nginx:
    volumes:
      - ./nginx/ssl:/etc/ssl
      - /path/to/external/letsencrypt:/etc/letsencrypt

If your configuration handles certificates entirely within the Certbot container, the official mounts may be fine as-is. However, if you manage certificates via external paths, it’s safer to review after replacement.

6. Update Sandbox Configuration #

A commonly overlooked aspect is Sandbox configuration. When versions change, Python / Node.js path assumptions may shift, and existing config.yaml files are not automatically updated.

app:
  port: 8194
  debug: true
  key: dify-sandbox

python_path: /opt/python/bin/python3
nodejs_path: /usr/local/bin/node

7. Syntax Check Before Startup, Log Review After Startup #

After replacing the compose, first run syntax checks. Then fetch images and start the services.

docker compose --profile weaviate --profile postgresql config > /tmp/dify.check.yaml

docker compose --profile weaviate --profile postgresql pull
docker compose --profile weaviate --profile postgresql up -d --remove-orphans

docker compose ps
docker compose logs --tail=120 api worker worker_beat plugin_daemon sandbox weaviate nginx

In update work, it’s critical not to assume success just because startup works. Logs from api, worker, worker_beat, plugin_daemon, and sandbox are particularly useful for early detection of functionality failures.

8. Post-Update Verification Checklist #

• Admin console login works normally
• Chat responses from existing applications return normally
• Knowledge search and reindexing succeed
• Code node and Sandbox execution succeeds
• Plugin activation and execution succeeds
• HTTPS delivery and certificate reference work without issues

In updates with large peripheral component differences like this one, the UI opening and all required functions working in production are separate issues. Determining key verification items upfront based on your usage makes rollback decisions easier.

Common Pitfalls Summary #

Lessons from This Update #

The longer a Dify environment runs, the more impactful “accumulated custom differences” become compared to “version numbers” at upgrade time. What we reaffirmed this time is that minimizing official compose modifications and managing environment-specific settings as overlays makes subsequent upgrades and incident response dramatically easier.

If your current environment is running stably on an older version, organizing just these three points before updating makes the process much smoother.

• Inventory and separate official-sourced settings from company-specific ones
• Always take rollback-capable backups
• Decide on key feature verification items before startup verification