Deployment Methods
Install Older Version
Use the --branch flag to install a specific version:
The rest of the setup is identical to installing the latest version.
Install Using ZIP Archive
For network-restricted environments or when git is unavailable:
Alternatively, download the ZIP on another device and transfer it manually.
To upgrade:
Clone Fails with “Remote branch null not found”
The clone command in Deploy Dify with Docker Compose resolves the latest Dify version through the GitHub API. When that request fails (usually due to GitHub’s rate limit on unauthenticated requests), jq outputs null, and git reports fatal: Remote branch null not found in upstream origin.
Clone with an explicit version instead. Find the latest version number on Dify releases, then run:
Cloning without --branch also works. The Compose file on main pins the latest released images, so you still run release builds, but the deployment files themselves (the Compose file and environment templates) track development and can drift from the tagged release.
Backup Procedures
Create Backup Before Upgrading
Always backup before upgrading to prevent data loss:
This creates a timestamped backup for easy restoration.
Reverse Proxy Setup
Login Session Drops with Split Frontend and Backend Subdomains
If you have split web and API across subdomains behind a reverse proxy (for example, app.example.com for the UI and api.example.com for the backend), authentication cookies cannot reach both hosts. Login appears to succeed, but the session is dropped on the next request.
Set both variables in .env, then restart Dify:
COOKIE_DOMAIN: set to the shared top-level domain (e.g., example.com). Leading dots are optional.NEXT_PUBLIC_COOKIE_DOMAIN: set to 1 to enable cross-subdomain cookies on the frontend.
Cookies cannot cross top-level domains, so the frontend and backend must share the same registrable domain. For full details, see environment variables.Last modified on August 21, 2026
