How to upgrade Dify Premium on AWS without losing configuration or data
If your team runs Dify Premium from the AWS Marketplace AMI on EC2 and needs to move to a newer release, the supported path is to follow the upgrade guide for the target version, and to take backups before you touch anything. The Dify Premium upgrade overwrites configuration templates on the instance, but it does not overwrite your .env file, your local envs files or the runtime data held in volumes. That split is what makes the upgrade safe to run, and it is also why backups come first: the files that survive are the files that carry your secrets, endpoints and application data, so a mistake there is hard to reverse. Minor Dify releases arrive roughly monthly (1.16.0 on July 17, 2026, then 1.17.0 on August 25, 2026), so a team that waits many releases will face a larger gap between its configuration and the target version.
Before the upgrade window, copy .env, the envs directory and every Docker volume that holds PostgreSQL, Redis, Weaviate or file storage data to a location outside the instance, and confirm that the copies can be read. Store SECRET_KEY with them, because changing it after deployment logs out all users and can break access to encrypted OAuth credentials. Then compare the current .env against the .env.example shipped in the target release, since new variables appear between versions and an unexplained gap there is a common cause of a failed start. Confirm with your AWS administrator that an EBS snapshot or AMI image of the instance exists and that the restore steps have been rehearsed on a copy, not only written down.
Plan the cutover around the components that depend on your settings. Decide who approves the window, which API keys and model endpoints must be re-tested afterward, and what rollback looks like if the new release does not start cleanly. If you have customized the compose file, record each change so it can be reapplied to the new template rather than assumed to persist. Check the release notes for the target version for security changes, since the 1.16.1 notes, for example, describe agent sandbox network isolation through a Squid proxy and token-based API authentication between services, and those can affect outbound traffic and internal integrations. Ask the Dify Premium documentation owner or your AWS partner to confirm the exact sync and restart steps for your AMI version before the window.
What changes between Dify releases and what it means for an AMI deployment
This table lists the Dify releases in the supplied notes, from 1.16.0 through 1.17.1, and sets out what each means for a Dify Premium EC2 host and what to do before or after moving to it. Read each row as a checkpoint for your upgrade plan, and confirm every item against the release notes for the exact version you target.
| Release | Change relevant to an AMI host | Action needed |
|---|---|---|
| 1.16.0 (July 17, 2026) | Minor release in the roughly monthly cadence; no specific breaking changes are documented in the notes used for this page | Read the 1.16.0 release notes on GitHub, back up .env, envs and volumes, then compare your .env against the current .env.example |
| 1.16.1 agent sandbox network isolation | Agent sandbox traffic is routed through a Squid proxy, which changes how agents reach outside services on the host | Test every agent that calls external URLs or internal services, and confirm the proxy allows the destinations your workflows need |
| 1.16.1 token-based API authentication | Services authenticate to each other with tokens, so any custom integration that calls internal endpoints may need credential updates | Confirm which of your scripts, sidecars or reverse proxy rules call internal Dify services and update them before cutover |
| 1.16.1 sandboxed Jinja2 rendering | Template rendering runs inside a sandbox, so templates that depend on unrestricted Python behavior may fail or render differently | Retest prompt templates and workflow nodes that use Jinja2 with representative inputs in a staging instance |
| 1.17.0 (August 25, 2026) | Minor release following the 1.16 line; the notes used here do not list additional AMI-specific changes | Check the 1.17.0 release notes, diff .env.example for new variables, and confirm your restart uses the override file |
| 1.17.1 (September 10, 2026) | Follow-on patch release; the notes used here do not list additional AMI-specific changes | Confirm you are on the intended patch level, rerun your smoke tests, and record the version in your change log |
What to back up and inventory before the upgrade
Dify Premium on AWS keeps its state in files and volumes that the upgrade does not replace, so the work before the upgrade is mostly about knowing what those items are and holding a copy of each. The cards below cover the configuration files, the runtime data, the local customizations and a rehearsal on a test instance.
Back up the .env file
The .env file holds the variables that configure your Dify Premium instance, including the SECRET_KEY. The upgrade leaves this file in place, so it is not overwritten, but you still need a copy you can restore if a template change or a manual edit goes wrong. Store the copy outside the instance, with the same access controls as other secrets. Record the file's checksum so you can confirm the copy matches. Before the upgrade, compare the current file with the .env.example shipped in the new version and note any new variables you will need to add.
Back up the local envs files
Dify Premium keeps local envs files alongside the configuration, and the upgrade does not overwrite them. Copy every such file with its directory path and permissions, because some of them may hold values set by your team that exist nowhere else. Confirm the list with the Dify Premium docs for your version rather than relying on file names from an older instance. Keep the copies with the .env backup so that one restore step brings back the full configuration set.
Back up the runtime data volumes
Runtime data lives in Docker volumes on the instance, including the PostgreSQL database, the vector store and uploaded files. The upgrade leaves these volumes intact, which is why a failed migration can still leave you with data that needs recovery. Stop the containers that write to the volumes before copying them, so the snapshot is consistent. Ask your team to confirm which volumes hold the metadata database and which hold knowledge base content, and test that a restore from the copy brings back the same apps and datasets.
Inventory docker-compose.yaml and override changes
Any edits to docker-compose.yaml and to the override file are yours to reapply after the upgrade, since the template changes underneath them. Write down each changed service, port, volume mount, environment entry and image tag, and why it was made. Keep the override file under version control or in a dated copy so you can diff it against the new template. Look for changes that conflict with new services or variables in the target release, such as an added plugin daemon or sandbox setting, and mark them for review before the restart.
Rehearse on a test instance
Launch a test instance from a snapshot of the same AMI version, restore the .env, envs files and volumes onto it, and run the full upgrade there first. This is illustrative of the practice rather than a fixed procedure: the test shows whether your customizations survive, whether the migration completes on your data size and how long the restart takes in your VPC. Keep the test instance isolated from production model credentials and from users, and compare app behavior and knowledge base queries before and after the upgrade.
What the Premium AMI upgrade overwrites and what it keeps
The Dify Premium AMI upgrade splits the instance into two groups. The upgrade overwrites the configuration templates shipped with the AMI, while it keeps your .env file, your local envs files and the runtime data in Docker volumes. The Premium documentation tells operators to back up .env, envs and the volumes before starting, which means the preserved items are still your responsibility if something goes wrong. Treat the backup as the rollback point, not as a formality.
The practical risk is assuming that any edit you made to a template file will survive the sync. Templates such as the Compose definition or other shipped configuration files can be replaced with the new release's version, so a change to a service's port mapping, volume path, resource limit or proxy setting may silently disappear. Before the upgrade, list every file under the docker directory that differs from the shipped copy, and confirm with Dify which of those files the upgrade replaces. Keep those changes in a separate override or a documented patch so they can be reapplied after the sync.
After the sync, check .env.example in the new release against your .env. The Dify Compose documentation advises checking for new variables after any upgrade, and a new release can add settings that default to something unsuitable for your environment, such as storage, sandbox or proxy options. Compare the two files line by line, add only the variables you need, and confirm that existing values such as SECRET_KEY were not changed. Then restart with your override file applied and verify the services before you reopen access to users.
Upgrade sequence: backup, sync the docker directory, restart with the override file
This sequence moves a running Dify Premium instance to a newer release by backing up configuration and data, syncing the new docker directory, and restarting with the override file. Each stage ends with a rollback point, so a failed check returns the instance to a known state. Work through the stages in order and close each one before starting the next.
Confirm the target release
Open the Dify releases page on GitHub and identify the version you are moving to, then read the release notes for every release between your current version and the target. Note any items about environment variables, storage, database migrations or the plugin daemon, because they change the backup and restart steps. Confirm in the Dify Premium guide that the AMI you are using includes the target release. Done when you have a written version pair, a list of release-note items that affect this instance, and a named owner who approved the change.
Back up .env, envs and volumes
Stop the stack first so the PostgreSQL files and other data do not change during the copy. Then copy the
.envfile, the envs directory, the current docker directory and the Docker volumes that hold database files, uploaded files and vector data to storage outside the instance. Confirm the volume names withdocker volume lsand the paths in the Dify Premium guide. Record a checksum for each copy. Done when a test listing or restore of each copy shows the files are complete. These copies are the first rollback point, since they restore configuration and data even if the snapshot step is skipped.Snapshot the EC2 instance
While the stack is still stopped, create EBS snapshots of every volume attached to the instance, including the root volume. The stopped state keeps the on-disk data consistent. Tag each snapshot with the instance ID, the current Dify version and the target version. Done when every snapshot shows a completed state in the EC2 console. This is the broadest rollback point: restoring these snapshots returns the disk to its pre-upgrade state, including operating system and Docker state that the file copies in the previous step do not capture.
Copy the new docker directory
The upgrade overwrites configuration templates but leaves
.env, the local envs files and runtime data in volumes alone. Copy the docker directory from the new AMI or release package over the current one. Keep your.envand envs directory in place, and do not copy the old templates back over the new ones. Compare the new directory with your saved copy to list every file that changed. Done when the change list contains only the template files you expected. Rollback point: if the list contains unexpected changes or the copy fails, restore the saved docker directory from the backup stage.Reapply template edits and diff environment
Reapply your customizations to the new compose templates, such as port mappings, certificate mounts and resource limits, using the saved copies as the reference. Then diff
.envagainst the new.env.exampleand decide for each added or renamed variable whether to set it. Do not changeSECRET_KEYduring this stage, because changing it logs out all users. Done when every template edit and every new variable has a recorded decision. Rollback point: restore.envand the saved docker directory from the backup stage if any decision cannot be justified.Restart with the override file
Start the stack with the compose command and override file that the Dify Premium guide specifies, pulling images first if the guide calls for it. Confirm the exact file name and command in the guide before you run them. Watch the api, worker and plugin daemon logs until they settle. Done when every container reports running and the logs show no startup errors from the migration or plugin services. Rollback point: if containers fail to start, stop the stack, restore the saved docker directory and
.env, and start again from the saved configuration.Run health checks and sign in
Open the console at the same address users use, sign in, and open an existing app to confirm it loads and runs. Test one knowledge base retrieval, one model provider credential and one plugin-backed tool, and confirm the worker processes queued jobs. Done when these checks pass and the logs show no new errors during the observation period set in your change record. Rollback point: if checks fail after the database migration has run, restore the saved volumes and the snapshot, because rolling back the code alone may not reverse database changes. Confirm the rollback order with the Dify Premium guide before you need it.
Testing the upgraded instance and rolling back safely
Before touching production, run the upgrade on a clone of the instance. Take a snapshot of the EC2 volumes, launch a separate instance from that snapshot in a non-production subnet, and apply the same upgrade steps you plan to use in production. Keep the clone's network isolated from real users and from production model credentials where your policy allows, so that test traffic cannot reach live data sources or trigger live actions. The goal is to confirm that the new release starts cleanly with your real configuration and data, not with a fresh default install.
- Log in as an administrator: Confirm that the console loads over the expected URL, that existing accounts sign in, and that workspace data is visible.
- Run a workflow end to end: Execute a representative workflow that calls a model, uses a tool and writes an output, and compare the result with the pre-upgrade run.
- Query a knowledge base: Run a retrieval test against an existing knowledge base and confirm that the expected documents are returned.
- Test model provider connections: Validate each configured provider credential from the model settings page, since provider changes are a common failure point after a version jump.
- Check plugin daemon status: Confirm the plugin daemon container is running, that installed plugins load, and that the logs show no repeated errors.
Record the results for each check so that the production run can be compared against them.
An in-place upgrade runs against the production instance after the clone has passed. Confirm that the pre-upgrade snapshot and the backups of .env, the envs files and the Docker volumes exist and are readable before any change is made. Keep the old configuration available so you can compare it with the new template output. Apply the upgrade steps in the same order you tested, and do not begin user-facing checks until the containers report healthy.
- Confirm the rollback point first: Verify that the snapshot and the copied
.env,envsand volume data are complete before stopping services. - Compare configuration after the sync: Diff the new environment file against the backup and confirm that only intended variables changed.
- Restart with the override file: Bring the stack up with the override file in place and check that the expected services are running.
- Repeat the test checklist: Run the same login, workflow, knowledge base, provider and plugin daemon checks used on the clone.
- Watch logs during a supervised window: Keep the API and worker logs open while users are reconnected so that errors appear while the change is still easy to reverse.
Do not declare the upgrade complete until every check matches the clone results.
If a check fails, decide quickly whether to fix forward or roll back. Fix forward only when the cause is clear, small and verified in a clone. Otherwise, restore the snapshot or the backed-up volumes and configuration files, and restart the previous state. Avoid partial restores where the database has moved forward but the configuration has not, because mismatched state is harder to diagnose than either version alone.
- Stop the stack before restoring: Bring services down so that no container writes to volumes during the restore.
- Restore the snapshot or volumes: Recover the EC2 snapshot, or restore the saved volume data and the original
.envandenvsfiles together. - Reapply the original override file: Confirm that the override file matches the previous version so the restored stack starts with the same service layout.
- Re-run the checklist on the restored instance: Verify login, a workflow run, a knowledge base query, provider connections and plugin daemon status before allowing users back.
- Record the failure: Keep the logs and the failed check details so that the retry runs against the cause, not against a guess.
Confirm with Dify's upgrade guide for the target version whether any data migration has already run, because that determines whether a restore alone is sufficient.
What makes a Premium AMI upgrade take longer
This table lists the factors that raise or lower the effort of a Dify Premium AMI upgrade on EC2, and how each one changes the work. Read each row as a question to answer about your own instance before you plan the window, since most of the effort sits in data volume, customization and the number of environments that must match.
| Effort driver | How it raises or lowers effort | What to check first |
|---|---|---|
| Data in the volumes | Larger volumes take longer to back up, copy and verify before the upgrade, and a restore from a large snapshot takes longer if a rollback is needed. | Size the volumes and confirm the backup target has room for a full copy before the change window. |
| Customized templates and overrides | Each edited configuration template or override setting must be compared against the new release, because the upgrade overwrites templates and your changes can be lost or conflict. | List every edited template and the override file, and record why each change exists. |
| External PostgreSQL or object storage | Moving the database or file storage outside the instance adds steps for backups, network access and credential checks, but the local volumes shrink and the work on them drops. | Confirm which services run locally and which point to external endpoints, and whether those endpoints need their own backup plan. |
| Model provider credentials | Each provider credential in use should be tested after the upgrade, so more configured providers means more test cases and more time before sign-off. | Count the providers and models in active apps and assign an owner to test each one. |
| Agent sandbox behavior | Sandbox and network isolation changes can block tools or outbound calls that worked before, so agent workflows need functional testing, which adds effort when many agents use external tools. | Review the release notes for the target version and list agents that call external services or run code. |
| Environments kept in step | Every extra environment (for example, development, staging and production) needs the same backup, sync and restart steps, and drift between them makes the next upgrade harder. | Confirm which environments run the same release and the same override file, and upgrade the lowest one first. |
Questions teams ask before upgrading Dify Premium on AWS
What drives the cost or effort of a Dify Premium upgrade on AWS?
The main drivers are how much customization sits on the instance, how many services and data stores your deployment depends on, and how much testing your team needs before production. An instance with customized configuration templates, external integrations, or a bundled Weaviate volume with a large dataset takes more planning than a lightly changed one. Release notes for the target version also matter, because a jump that touches the plugin architecture or vector store client needs more verification than a routine minor release. Ask for a written scope that lists the environments, the backup steps, the validation checks and the rollback plan, since those items set the effort.
Can our internal team run a Dify Premium AMI upgrade without outside help?
Yes, if your team has AWS EC2 operations experience, can read Docker Compose files, and can test the application after the change. The Dify Premium docs say the upgrade overwrites configuration templates but keeps .env, local envs files and runtime data in volumes, so the steps are well defined. The harder parts are checking what your environment customized, confirming that the new docker directory and .env values are compatible, and proving that apps, knowledge bases and model connections still work. Teams that have no staging copy or no one to own rollback usually benefit from an outside review of the plan.
What does the upgrade need from our team before work starts?
You will need administrative access to the EC2 instance, the VPC and any related AWS resources such as snapshots, storage and load balancers. You will also need a change window that allows for a backup, the upgrade and a test pass, plus a named owner who can approve a rollback. Test data matters: sample workflows, knowledge bases and model configurations that represent real usage let you confirm the upgrade worked, without exposing production records. Your security team should confirm how secrets in .env are stored and who may view them during the work. List these needs in the written scope so they are scheduled before the upgrade day.
How long does a Dify Premium upgrade take, and why is no figure given without scope?
No duration is published here because the time depends on the instance size, the volume of data in the volumes, the number of customizations, the test coverage required and the target version. A minor upgrade with a small dataset and no custom changes takes far less time than a version jump with customized templates and multiple environments. The Dify docs recommend backing up before every upgrade, and backup time grows with data volume. Ask for a timeline in the written scope, which should state the assumptions behind it, so you can compare it with your own estimate.
Is a backup of `.env`, envs and volumes enough to protect an upgrade?
A backup is necessary, but it does not confirm that the upgraded system works. The backup lets you restore the previous state if something fails, and it covers the files the upgrade keeps and the runtime data in volumes. Verification is still needed: check that the services start, that the docker directory matches the new release, that the override file is applied on restart, and that workflows, knowledge bases and model connections respond. Store backups outside the instance, and test a restore on a separate host if your change process requires proof that recovery works.
Which parts of the upgrade should we check after the restart?
Start with the services. Confirm that the containers come up with the override file applied, then review logs for database, storage and plugin errors. Next, check the application paths your users depend on, such as sign-in, a workflow run, a knowledge base query and a model call. Compare the .env values against .env.example in the new release, since the Dify Docker Compose docs advise checking for new variables after an upgrade. Finally, confirm that secrets such as SECRET_KEY are unchanged, because changing it logs out all users.
Does the Dify Premium upgrade change our licensing or support position?
The upgrade itself does not change the license terms, but your deployment must still follow them. Dify is released under a modified Apache License 2.0 that restricts operating a multi-tenant environment without written authorization and prohibits removing or modifying the logo or copyright information in the console. Confirm with your vendor and legal team what your Premium subscription covers, including support, before you plan the work. DeployOpen's scope for an upgrade is defined in writing and does not replace the vendor's terms.
Where DeployOpen fits in an AMI upgrade
DeployOpen plans, backs up, upgrades, documents and supports self-hosted platforms inside your own AWS account, so an AMI upgrade of Dify Premium can be run as a scoped piece of work in the environment you already operate. The AMI runs as an EC2 instance in your VPC, which means the instance, its attached volumes, the .env file and the local envs files all stay under your control throughout. Before any work starts, the reader should confirm who holds the AWS account, who can approve a maintenance window, and who owns the backup target, because those answers decide what a partner can touch and what your team must sign off.
Most DeployOpen engagements are fixed-scope, so the scope, deliverables and timeline are agreed in writing before the upgrade begins. For this topic, a written scope would normally name the target Dify version, the backup and restore evidence to be produced, the check of .env against the new template, the reapplied override file, and the post-upgrade verification steps. Ask for the written scope to state which of these items are included and which remain with your team, and ask how a rollback is handled if the restart fails. Ongoing support, upgrades and continuous testing are available as retainers, which suits teams that expect to take several minor releases a year. DeployOpen does not publish a price list, so a quote follows from the written scope rather than from a standard rate card.
How DeployOpen works on this
DeployOpen plans and carries out Dify Premium on AWS upgrades inside your own AWS account and VPC, starting from a written scope. We work through the backup, sync and restart steps against your current configuration, test the result in conditions you define, and hand over a runbook your team can repeat. Ongoing upgrades and support are available as a retainer.
How we scope
- We confirm the current Dify Premium version, the target version and the EC2 instance layout before any work starts.
- The written scope lists which .env values, local envs files and volumes are in play and who owns each backup.
- We record customizations to docker-compose files and the reasons they exist, so they can be reapplied after the sync.
How we build
- We take and verify backups of .env, envs and volumes before changing anything on the instance.
- We sync the new docker directory and compare overwritten templates with your saved versions, reapplying approved changes.
- We restart the stack with the override file in place and check that the api, worker and web services come back healthy.
How we hand over
- You receive a written runbook covering backup, sync, restart and rollback steps for your specific instance.
- We document which files the upgrade overwrites and which it keeps, so later operators do not have to rediscover them.
- We walk your platform and operations staff through the runbook and the post-upgrade test results before closing the engagement.
How we support
- Ongoing upgrades, updates and monitoring of future Dify releases can be covered by a retainer agreed in writing.
- Before each future release, we review its release notes and .env.example changes against your environment.
- Support scope, response expectations and test cadence are set in the retainer, so you can confirm them before signing.
