Promoting Dify apps from staging to production on Community
A team running Dify Community in a single workspace needs a controlled way to move tested apps into production, and on Community that promotion is a manual release process. It is built from separate staging and production instances, DSL files kept in Git and documented version names, because Enterprise Environments are not available. The Community edition is free and limited to one workspace, so there is no built-in way to hold a staging and a production copy side by side in the same console. Each instance is its own deployment with its own database, storage and secrets, and the team has to design the handoff between them.
The DSL export is theunit of promotion, but it is not a full copy of an app. According to the Dify docs, an export carries the app configuration, workflow nodes, model parameters, prompts and knowledge base connections. It does not carry third-party API keys, knowledge base content or usage logs. The team must therefore plan credentials and data separately: each instance needs its own model provider keys and any tool credentials entered in its console, and the knowledge bases behind a promoted app must be populated on the production instance through a separate, documented step. Confirm with your own environment which connections an imported app will need re-entered before the first release.
Rollback follows the same logic. Before each promotion, record the DSL version name, the release notes and the Dify version on both instances, and keep a backup of the production database and storage so the previous state can be restored. Because the Dify upgrade guidance recommends a backup before every upgrade, the same discipline should apply to every app release. Confirm with your team which backup method and retention period you will use, since those choices determine how far back a rollback can reach.
Promotion options on Community and when each fits
This table compares three ways to move a Dify app from staging to production on Community, scored on isolation, credentials, data residency, effort and drift. Read each row as a trade-off: the option with fewer moving parts is usually the one with weaker separation between test and live data. The main takeaway is that two separate instances with DSL promotion gives the cleanest boundary, while a single instance is only defensible for low-risk apps with strict change control.
| Option | Isolation and credentials | Data residency and effort | Drift risk and when it fits |
|---|---|---|---|
| One instance, two apps | Staging and production apps share one workspace, one database and one set of model provider credentials, so a test change can reach live data | Lowest setup effort, but one upgrade and one backup cover both environments, and test data sits next to production data | Drift is limited to app settings, but a shared instance is hard to justify for regulated workloads; use only for internal, low-risk apps |
| Two separate instances with DSL promotion | Each instance has its own database, SECRET_KEY, provider keys and end-user access, so staging credentials never reach production | Two sets of infrastructure to run and back up, with DSL files in Git as the transfer path; provider keys are re-entered per instance | Drift is controlled by re-exporting from staging and reviewing the diff; this fits teams that need a clear boundary and a repeatable release path |
| Single instance with manual copies | Apps are duplicated by hand inside one instance, so separation depends on naming and discipline rather than system boundaries | Little infrastructure cost, but copying prompts, workflows and settings by hand is slow and error-prone | Drift is highest because no artifact is kept; suitable only for short-lived prototypes that will be rebuilt before production use |
Setting up the release process step by step
This sequence turns a Community deployment into a repeatable path where an app is built and tested on staging, exported as reviewable DSL, and imported into production with production-only credentials and a documented way back.
Deploy separate staging and production instances
The operator runs two Docker Compose deployments of Dify, each with its own
SECRET_KEY, PostgreSQL database, Redis, and file storage, and records which instance holds which role. Keep the two.envfiles separate so a value copied to one cannot silently apply to the other. Done when staging and production both reach the console, and each shows its own empty workspace. ChangingSECRET_KEYafter deployment logs out all users, so generate it once per instance and store it in your secrets manager. Confirm the deployment steps and version pinning against the Compose documentation before you start.Agree the DSL naming and version convention
Platform and app owners agree on how exported files are named, for example by app name, a version label, and the Dify release the app was built on, and how version names appear in the console. Write the convention in the repository README so every reviewer applies it the same way. Done when a sample file name and version label can be read by someone who did not build the app. The convention is yours to set; Dify does not enforce one for DSL files.
Create the Git repository and review rules
Create a repository that holds one DSL file per app, a short release note per change, and a change log. Protect the main branch so a change reaches production only through a reviewed merge, and require reviewers who know the model and knowledge base choices. Done when a test change to a DSL file triggers the review rule and cannot be merged by its author alone. Ask your Git platform's administrator to confirm branch protection settings for your plan.
Export the app from staging into the repository
An app builder publishes the staging version, exports it as YAML DSL, and commits the file with the agreed name and a release note. Review the diff for prompts, model parameters, and knowledge base references, and check that no secret has been typed into a prompt or tool field. Done when the commit exists, the reviewer has approved it, and the release note states what changed. Dify exports include app configuration, workflow nodes, model parameters, prompts, and knowledge base connections, but not third-party API keys, knowledge base content, or usage logs, so the file alone will not move data.
Import the DSL into production and bind credentials
An operator imports the approved DSL file into the production workspace, creating a new app or updating the existing one. Then configure model provider keys, tool credentials, and any external service secrets directly in production, outside the DSL. Done when the imported app's model settings point to the production provider configuration, each knowledge base connection resolves to a production dataset, and the app runs without errors on the draft. Check each model and knowledge base binding by hand, because an import can reference names that exist only in staging.
Run smoke tests before publishing
A tester runs a fixed set of prompts and workflow inputs against the imported production draft, including edge cases and an input that should be refused, and compares outputs with the staging baseline. Confirm retrieval returns content from the production knowledge base and that API calls, if used, succeed with the production app key. Done when the test results are saved with the release record and the owner signs off. Publish only after the sign-off, since publishing makes the version visible to users of the app.
Publish and record the release
The owner publishes the production version and records the version name, the Git commit, the Dify release in use, and the smoke test results in the release notes. Done when the console shows the new version as current and the repository tag matches it. Keep the previous published version available in the console so it can be restored.
Document and rehearse the rollback
The team writes the rollback steps: restore the previous published version of the app in production, confirm the model and knowledge base bindings again, and log the incident. Take a backup of the production database before each release, because Dify recommends backups before upgrades and a restore is the fallback if a version fails in ways a version restore does not fix. Done when someone other than the release owner has walked through the steps on a test app and confirmed the expected output. Ask your operations team to confirm how backups are scheduled and tested in your environment.
What each release record must contain
A release record ties one DSL export to the exact platform and configuration it was tested on. Each field answers a question someone will ask during a rollback, an incident or an audit, so the record should be complete before the promotion starts.
DSL file and version name
The exported YAML DSL file, stored under a version name that both instances use, such as a date plus a sequence number. Dify exports carry app configuration, workflow nodes, model parameters and prompts, so the file is the artifact that moves. Record the app ID and the name of the file in Git so the same file can be found again during a restore.
Dify version on both instances
Record the Dify version running on staging and on production at the moment of export and import. Minor releases arrive roughly monthly, and an app can behave differently across versions, so a DSL tested on one version may not behave the same way on another. If the versions differ, the record should say which side must be upgraded first and whether the test was repeated afterward.
Git commit reference
The commit hash in the configuration repository that holds the approved DSL file, plus the commit that updated any deployment files. The commit lets the team confirm which file was live before a change and roll back to that exact state. Tag the commit with the version name so the record and the repository point to the same version.
Change summary
A short description of what changed in the app, written for someone who did not build it. List changed prompts, model settings, workflow nodes and tool bindings. Note anything that changed in behavior for end users, because the summary is the first thing an approver reads when deciding whether the release is safe.
Knowledge base reconnections
Exports do not carry knowledge base content, so every knowledge base the app depends on must be reconnected on the target instance. List each knowledge base by name, its target equivalent, and the person who completes the reconnection. Confirm the retrieval results on production match staging before the app is published.
Credentials to recreate and test results
List every third-party API key and model credential the app needs, and confirm that each is created separately on the target instance rather than copied from staging. Attach the test results for the release, covering the workflows run, the expected outputs and any failures accepted. Without these two items, the record cannot show that the promoted app works on production.
How rollback by version restore works in practice
Rollback on Community means importing a prior DSL version into production and publishing it again. Dify's DSL export carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections. It does not carry third-party API keys, knowledge base content or usage logs. A restore therefore brings back the app's logic and settings, while everything the app depends on at runtime stays where it is. Before you plan a rollback, list what changed between the two versions and check each change against that boundary. If a release altered a knowledge base connection, a model selection or a credential reference, the restored DSL will point at whatever exists in production today, and the team must confirm that those targets still behave the same way.
The Dify Docker Compose documentation recommends a backup before every upgrade, and the same discipline belongs before any promotion that changes production. A DSL file is a copy of the app, not a copy of the instance. Before you publish, take a backup of the production database and file storage so that knowledge base documents, uploaded files and conversation history can be recovered independently of the app definition. Store the .env file and secret values under the same change record, because the environment variable reference notes that changing SECRET_KEY after deployment logs out all users and affects encrypted OAuth credentials. Confirm your backup restores into a separate instance before you rely on it, and record the Dify version running in production so that a restored DSL is never imported into a different release without review.
Questions teams ask before promoting Dify apps
How much does it cost to promote Dify apps from staging to production on Community?
The software is free to use on the Community edition, so the cost is staff time, infrastructure for two instances, and any outside help. The self-hosted Community edition is free and limited to a single workspace, according to the Dify pricing page. Costs recur through hosting, model provider usage, and the time spent on each release. Drivers include the number of apps, how many instances you run, how much testing each release needs, and how often Dify ships minor releases. Ask any partner for a fixed-scope quote built from a written list of environments, apps and deliverables.
Can our in-house team run a Dify release process without outside help?
Yes, if you have people who can operate Docker Compose, manage secrets per environment, and review exported app definitions. The process relies on ordinary practices: separate instances, DSL exports committed to Git, named versions with release notes, and rollback by restoring a known version. The harder parts are disciplined testing of each promotion and keeping staging close to production. Teams with no one who runs Docker or Git day to day should plan for training or a partner for the first cycles. Confirm your own skills against the work before you decide.
How long does it take to set up a promotion process for Dify?
Duration depends on how many environments you already have, how many apps need promoting, and how much of the deployment is already automated. Setup covers two Docker Compose instances, a Git repository for DSL exports, a naming scheme for versions, and a written rollback procedure. Each app then needs a first promotion and a test pass. No fixed figure applies to every team, so ask for a timeline in the written scope and check it against your change calendar and staff availability.
What does our team need to provide before the work starts?
Plan to provide separate staging and production hosts that meet the Community requirements, access to your Git hosting, and an owner for each app. You will also need the model provider contracts and API credentials for each instance, since Dify exports do not include third-party API keys. Also provide the list of knowledge bases each app uses, because exports do not carry knowledge base content. Confirm change approval rules and where backups are stored before the first release.
Does a DSL export contain everything needed to promote a Dify app?
No. According to the Dify docs, an export includes app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but not third-party API keys, knowledge base content or usage logs. Each instance therefore needs its own credentials, and the knowledge base data must be handled separately. Treat the DSL file as configuration that is reviewed and versioned, not as a full backup. Check each release for the items the export leaves out before you declare it promoted.
What are the risks of promoting Dify apps without a defined rollback?
The main risk is a broken workflow reaching users with no quick way back. A rollback by version restore depends on a recent backup and a tested procedure, and Dify's Docker Compose docs recommend a backup before every upgrade. Other risks include a secret key change that logs out all users, and a Dify release that adds new variables to .env.example that were missed in one instance. Write the rollback steps, test them on staging, and record which version each instance runs.
When is outside help worth it for Dify promotion work?
Outside help is worth considering when the team lacks Docker, Git or secrets management experience, when the first promotions carry high business risk, or when several apps and environments must be governed at once. It also helps when you need a documented process your auditors can review. Ask for a written scope that covers environments, deliverables, testing and handover. Be cautious of any promise that a process will remove all risk. Compare the quote with the staff time your team would otherwise spend learning the process.
How DeployOpen scopes and supports Dify release processes
DeployOpen plans, implements and documents the staging and production release process for self-hosted Dify inside your own infrastructure, so the instance separation, DSL export repository, version naming, per-instance credentials and rollback steps described on this page are built in your cloud account, data center or air-gapped network rather than in a shared service. Because Community is limited to a single workspace, the work usually centers on two separate Dify instances, each with its own database, secrets and storage, and on the handoff procedure between them. Scope should name which instances exist, where each runs, who approves a promotion, and which environment variables such as SECRET_KEY are set independently per instance.
Every engagement is scoped in writing before work starts. The written scope should list the deliverables, such as the Git layout for exported DSL files, the release checklist, the rollback runbook, the upgrade notes that accompany each Dify minor release and the handover material for your operators. It should also state what remains with your team, including who maintains model provider credentials, who reviews app changes and who owns access to each instance. Ask for the exact acceptance criteria in that document so both sides agree on what a finished release process looks like.
Ongoing support is available as a retainer for teams that need help when Dify ships new releases, which arrive roughly monthly according to the Dify releases on GitHub page. A retainer can cover reviewing upgrade notes, testing a promotion against staging before each production change and keeping the release runbook current. Confirm with DeployOpen what the retainer includes, response expectations and how changes to scope are priced before you sign, because those terms belong in the written agreement rather than in this page.
