Dify source code deployment for customization: when a fork is worth the upkeep
A fork is worth the upkeep only when a requirement cannot be met by configuration, plugins or the Enterprise edition, and the team accepts that every upgrade will be a merge. Running the Dify API, worker and web services from source, with the middleware stack in Docker, gives a team direct control over the application code. Dify is an LLM application development platform for building AI workflows, RAG pipelines and agents through a visual interface, with a prompt IDE, support for many model providers, LLMOps monitoring and backend-as-a-service APIs, according to the langgenius/dify repository. The source route is the path for changes to the core application itself, not for adding a model provider, a tool or an app setting, which the platform already exposes through its own mechanisms.
Before any code changes, the legal position needs a review. The Dify Open Source License is a modified Apache License 2.0 that forbids operating the source code as a multi-tenant environment, where one tenant is one workspace, without written authorization. It also forbids removing or modifying the logo or copyright information in the Dify console. A fork that is offered to other business units, subsidiaries or customers as a shared service may fall into the restricted case, so the legal and procurement owners should read the LICENSE file and confirm the intended use with the licensor in writing before the design is fixed. The community edition is also limited to a single workspace, so a multi-workspace requirement points toward the Enterprise edition rather than a fork.
Most needs are better met another way. Model connections, tools and data sources are usually handled through plugins, environment configuration and workflow design, and many identity and multi-workspace needs are covered by the Dify Enterprise SSO documentation and the Enterprise edition described on the pricing page. Confirm with the vendor which of these paths covers each requirement. Then record the cost of a fork as a recurring item: each minor release arrives roughly monthly according to the releases page, and every patched file must be reconciled with upstream changes, including security fixes.
Which platform changes justify a fork
A fork gives your team control over Dify's core code, but every changed line becomes work your team carries through each upgrade. Before you fork, check whether the need can be met by a plugin, a configuration setting or a DSL export, because those options survive upgrades with less effort.
Custom core API behavior
Changes to how the api service handles requests, authentication or response shapes touch code that moves with every release. First check whether a plugin or an app-level setting covers the need. If it does not, a fork is justified only for behavior that no extension point reaches, and the team should review each changed endpoint against the release notes for every upgrade. Fork only after an extension point has been ruled out.
Changes to the workflow engine
Workflow node execution, scheduling and variable handling are core logic that changes often. A custom node type is usually better built as a plugin, and a workflow pattern is usually better expressed as a DSL file. Changing the engine itself means your team must retest every existing workflow after each upgrade, because a fix in upstream code can alter outputs your apps depend on.
Custom storage or auth flows
Dify already supports several metadata databases, object storage providers and vector stores through environment configuration, and it supports SSO through its Enterprise edition. Rewriting storage or login flows in code means you own the security of those paths, including how SECRET_KEY and workspace encryption keys are handled. Confirm the configuration option first, and treat any custom auth code as a security-reviewed component.
Internal branding limits
The Dify Open Source License forbids removing or modifying the logo or copyright information in the Dify console. Branding changes that stay within the license are cosmetic, but a fork that alters those elements is outside the license terms. Ask counsel to review the exact change list before work starts, and keep the console attribution intact in every build.
Multi-tenant operation
The license forbids using the source to run a multi-tenant environment without written authorization, where one tenant is one workspace. A fork that adds workspace isolation to serve several business units or customers falls into this restriction. Use the Enterprise edition for multiple workspaces, or obtain written authorization, before building that capability into your own code.
Ownership after handover
Once DeployOpen hands over a forked codebase, your team owns every patch, merge from upstream and test run. Upstream releases arrive roughly monthly, so the fork accumulates drift quickly. Ask for a written list of changed files, a merge procedure and the test suite that proves each change still works, and confirm who will staff upgrades before the fork is approved.
Source deployment compared with Compose and Enterprise
This table compares the Compose image deployment, a source deployment with middleware in Docker, and Dify Enterprise on Kubernetes across customization depth, upgrade effort, licensing, workspace scope and code ownership. Read each row as a question to answer for your own team, and treat the Community limits as the constraint that often decides the path.
| Dimension | Docker Compose (images) | Source deployment (API, worker, web from code) | Dify Enterprise on Kubernetes |
|---|---|---|---|
| Customization depth | Configuration through environment variables and supported extension points only | Code changes to the API, worker and web services, plus any middleware changes you choose to make | Enterprise features and deployment layout delivered by the vendor, with customization through supported configuration |
| Minimum host requirements | At least 2 CPU cores, 4 GB RAM and Docker Compose 2.24.0 or later | Same Docker-based middleware baseline, plus a local runtime for the services you run from source | Kubernetes 1.24 or later and Helm 3.14 or later, with separate PostgreSQL, Redis, Qdrant and object storage |
| Upgrade effort | Pull the target release images, check .env.example for new variables and back up first | Merge upstream changes into your fork, resolve conflicts in custom code and retest each service before rollout | Helm chart upgrades on a planned release channel, with the vendor's upgrade guidance |
| Licensing constraints | Dify Open Source License applies; no multi-tenant operation without written authorization and logo or copyright must stay intact | Same license applies to modified source; keep the console logo and copyright notices and review what counts as multi-tenant | Commercial license under the Enterprise agreement, with the terms set in your contract (confirm scope in writing) |
| Workspace scope | Community edition is limited to a single workspace | Community limit applies to the code you run, so one workspace per instance unless you hold a suitable agreement | Multiple workspaces and SSO are part of the Enterprise edition |
| Who maintains the code | Your team maintains configuration and the upgrade runbook; the vendor maintains the images | Your team owns the fork, its patches, test suite and dependency updates for the life of the fork | The vendor maintains the application code; your team maintains the cluster, data stores and integrations |
| Middleware publishing | SSRF proxy and sandbox stay on the internal Compose network | The SSRF proxy and sandbox ports can be published on the host (EXPOSE_SSRF_PROXY_PORT, EXPOSE_SANDBOX_PORT), which widens the attack surface | Network policy and ingress are managed in the cluster; confirm the exposure model with the vendor |
| Best fit | Standard features, one workspace, and a team that wants low maintenance | A proven need for code changes that configuration and plugins cannot meet, with capacity to maintain them | Multi-workspace, SSO, high availability and a vendor-supported production footprint |
How upgrades get harder once you run from source
A source fork turns every Dify upgrade into a merge project. Dify minor releases have arrived roughly monthly: 1.16.0 on July 17, 2026, 1.17.0 on August 25, 2026 and 1.17.1 on September 10, 2026, according to the Dify releases page on GitHub. Each release has to be rebased or merged against your changes to the API, worker and web code, and the window between releases is short enough that a fork can fall behind within a single quarter if nobody owns that work.
The Docker Compose documentation gives operators a simple sequence: follow the upgrade guide for the target version on the GitHub Releases page, take a backup before every upgrade, and check .env.example for new variables. A source deployment has to repeat each step against its own diffs. Before you merge, confirm which upstream files your patches touch, back up the metadata database, object storage and vector store together, and compare the new .env.example with your environment file so that a renamed or added variable does not fail silently in your build.
Security changes are where a fork breaks without an obvious error. The 1.16.1 release notes describe agent sandbox network isolation through a Squid proxy, token-based API authentication between services and sandboxed Jinja2 template rendering. If your fork changed the sandbox networking, the service calls or the template code paths, an upstream change can leave a control missing while the application still starts and serves traffic. Plan a test for each of these controls on every rebase, and treat the release notes for each version as a required review item rather than optional reading.
Setting up the source deployment with middleware in Docker
This sequence brings up the Dify middleware containers in Docker, exposes only the proxy and sandbox ports you intend, and runs the API, worker and web services from a cloned source tree so each component can be verified before any customization starts.
Confirm host minimums and Docker Compose version
The platform engineer checks that the host meets the documented minimums of at least 2 CPU cores and 4 GB of RAM, and that Docker Compose is version 2.24.0 or later. Source deployment still depends on the same middleware, so a host below these minimums will fail in the same places as a Compose install. Record the Docker and Compose versions in the change ticket. The step is done when
docker compose versionreports 2.24.0 or later and the host resources are documented. Confirm sizing beyond these minimums with your own workload assumptions, since the minimums are only a floor.Clone the repository at the chosen release tag
The engineer clones the langgenius/dify repository and checks out a specific release tag rather than the moving main branch, so the source matches a version your team has reviewed. Pick the tag from the GitHub releases page and read its release notes for security changes and configuration variables before going further. Release notes for recent minor versions describe security changes such as sandbox network isolation and token-based service authentication, so the chosen tag determines which controls you inherit. The step is done when
git describe --tagsreturns the selected tag and the working tree is clean. Keep the tag and commit hash in your build record.Set the environment file and publish ports deliberately
Copy the example environment file in the docker directory to
.envand review it before starting anything. SetEXPOSE_SSRF_PROXY_PORTandEXPOSE_SANDBOX_PORTonly if your developers need host access to those services, because the source setup publishes them on the host by default (3128 and 8194 in the environment reference). ReplaceSECRET_KEYwith a value generated for this environment, since it signs sessions and JWTs and encrypts OAuth credentials. The step is done when the.envfile holds your chosen values and the port settings match a written decision about who may reach them.Start only the middleware containers
From the docker directory, the engineer starts the middleware services (PostgreSQL, Redis, the vector store and the SSRF proxy, plus the code sandbox where the release includes it) and leaves the api, worker and web containers stopped. Use the service names listed in the release's Compose file rather than starting the whole stack. Wait for each container to report healthy. The check is
docker compose psshowing the middleware containers as running or healthy, and the api, worker and web containers absent. Confirm service names against the local source code guide for your tag, because they vary between releases.Verify host ports and the proxy and sandbox boundaries
Before running any application code, the security engineer lists the listening sockets with a tool such as
ss -ltnpand confirms that only the intended middleware ports are bound to the host interface. Bind published ports to 127.0.0.1 where developers reach them locally. Then test that the SSRF proxy and sandbox accept traffic only from expected sources, for example by connecting from another host on the network and confirming the connection is refused. The step is done when the listening ports match the decision recorded in step three and the external test fails as expected. Record the result as evidence for the design review.Run the API, worker and web services from source
The developer follows the local source code guide for the chosen tag to install dependencies and start the API, the Celery worker and the web frontend from the cloned source. Each process should point at the middleware on the host through the environment variables the guide names. Start the services in the order the guide gives, so the API can reach the database before the worker starts consuming tasks. The step is done when all three processes stay running without repeated connection errors in their logs.
Verify each service responds
The engineer checks each component separately. Request the API health or console endpoint, confirm the worker reports that it is connected to the broker and ready for tasks, and load the web interface in a browser to confirm it can sign in and reach the API. Then check the middleware connections from the API logs, including the database and Redis. The step is complete when each service returns its expected response and the logs show no errors on startup. Save the outputs as a baseline so later customization can be compared against a known working state.
Securing the published middleware ports and secrets
A source-code deployment publishes middleware ports on the host that the full Compose stack keeps internal, so the host network and secret handling become your responsibility. The cards below cover the exposed ports, the keys that protect sessions and stored credentials, the outbound proxy, and the secret storage practices that keep configuration out of version control.
Restrict the published proxy and sandbox ports
In a source-code start, the SSRF proxy and the code sandbox are published on the host through EXPOSE_SSRF_PROXY_PORT (default 3128) and EXPOSE_SANDBOX_PORT (default 8194). Any host interface that accepts traffic on these ports exposes an open proxy or a code execution service to the network. Bind them to 127.0.0.1 or a private interface, and confirm with your network team that host firewall rules block them from other subnets.
Keep SECRET_KEY stable
SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials. Changing it after deployment logs out every user and can make stored OAuth credentials unreadable. Generate a strong value once, store it in your secrets manager, and make sure every rebuilt host, container or restored environment reuses the same value. Record the key's owner and rotation procedure before go-live.
Understand what SSRF_PROXY controls
The SSRF_PROXY settings route outbound requests from Dify through a proxy that blocks internal and private IP ranges. This protects workflows and tools that fetch URLs from reaching your internal services. Do not point Dify at an internal model endpoint or database through the proxy without a deliberate allow rule, and test whether your self-hosted model servers are reachable as the design expects.
Control workspace encryption keys
Workspace encryption keys can be stored locally or in Azure Key Vault. Local storage places key material on the same host as the database and file volumes, so a copy of the volumes can expose both. Confirm which option your environment uses, who holds access to the key store, and how backups of the key material are protected and restored separately from the data they decrypt.
Keep secrets out of source control
A source-code deployment means the working tree holds configuration, so the .env file, local overrides and any build scripts can accidentally contain SECRET_KEY, database passwords and model provider credentials. Add these files to .gitignore, scan commits for secrets, and inject values at runtime from your secrets manager. Check the repository history of any fork before sharing it.
Verify the port and secret controls
Before go-live, scan the host from a network outside the approved range to confirm the proxy and sandbox ports are closed, and confirm that a test session survives a restart with the same SECRET_KEY. Ask your security team to review the controls against your internal baseline. Schedule this check again after each upgrade, since upgrade steps can add or change environment variables.
Questions teams ask before running Dify from source
What does running Dify from source cost in effort, and who pays for it?
Running Dify from source moves cost from the license to engineering time. The Community edition is free to download and run, so the spend is people: engineers who clone the repository, build the API, worker and web services, maintain the middleware stack and carry every change forward. Some of that cost is one-time (the initial build, the first set of patches, documentation of the fork) and some recurs (testing each monthly minor release, rebasing custom code, rotating secrets, and reviewing security notes). Costs rise with the number of changes you carry, how often you track upstream, and how many environments you run. When you request a quote, ask for the effort split between initial build, upgrade cycles and ongoing support, and ask who owns the fork after handover. The Community edition is listed as free on the Dify pricing page.
How long does the initial source build take for a team new to Dify?
The duration depends mainly on the team's prior experience and the scope of the changes, not on a fixed number. A team that already runs Docker Compose, Python web services and Node-based frontends will spend most of its time learning how the api, worker, web and plugin components talk to each other. A team without those skills will also need to learn the middleware (PostgreSQL, Redis, the vector store and the sandbox) and the environment variables that control them. Other drivers include how many customizations are planned, whether they touch the workflow engine or only the interface, and how much testing the target environment requires. Ask any partner to break its estimate into discovery, build, verification and handover, and to tie each phase to the changes in your written scope.
What must our team provide before a source deployment starts?
Your team needs to supply four things. First, engineers who can own the code: at least one person who can read Python and TypeScript, operate Docker, and review changes. Second, a host or cloud account with enough capacity, since the self-hosting docs state a minimum of 2 CPU cores, 4 GB of RAM and Docker Compose 2.24.0 or later for the Compose deployment, and a source build adds build tooling on top. Third, a secrets process that sets SECRET_KEY and other credentials outside the repository. Fourth, model access: API keys or endpoints for the providers your apps will call, and a test plan that uses approved models. Confirm each item with your security team before work begins, especially where production data or private model endpoints are involved.
Can our own engineers run a source deployment without outside help?
Yes, a capable internal team can run a source deployment, provided it treats the work as a product it will maintain. Start with the local source code guide in the Dify documentation, then confirm that the stock build works in a test environment before changing anything. The harder part is ongoing: each release has security notes, such as the agent sandbox network isolation and token-based service authentication described in the 1.16.1 release notes, and your fork must be re-tested against them. Teams that lack capacity for monthly review cycles, or that need evidence of change control for regulators, often find that an outside partner is a better fit for the build and handover, even if internal staff keep operating the system.
When should we bring in an implementation partner for a Dify fork?
Bring in a partner when the fork is larger than a few isolated changes or when the team cannot absorb the upgrade load. Useful signals include planned changes to the API, worker or workflow code, a requirement to keep the fork aligned with releases that arrive about monthly, a need for documented security testing before go-live, or a deadline that internal capacity cannot meet. A partner can plan the change set, build and test it, document the upgrade path and hand over runbooks. DeployOpen works in your own infrastructure on fixed-scope engagements, with ongoing support and testing available as retainers. Ask for the written scope, deliverables and timeline before work starts.
Can we keep a modified Dify fork off a multi-tenant environment under the license?
Yes, the license places one clear limit on this use. The Dify Open Source License is a modified Apache License 2.0 that forbids using the source code to operate a multi-tenant environment, where one tenant is one workspace, without written authorization. It also forbids removing or modifying the logo or copyright information in the Dify console. A single-organization fork that runs in your own infrastructure, with one workspace for your teams, is the case the Community license is built around. If you plan to offer Dify to outside customers or to several business units as separate workspaces, you need written authorization or the Enterprise edition, which the pricing page lists with multiple workspaces. Have your legal team read the Dify LICENSE before any fork is shared.
What breaks most often when a Dify fork meets a new release?
The most common failures come from changes to environment variables, schema and service interfaces that your fork depends on. The Docker Compose upgrade guidance recommends a backup before every upgrade and a check of .env.example for new variables after each upgrade, which shows where drift starts. Forks also break when the database migrations change, when internal service authentication changes, or when a patched file no longer matches upstream code. Plan a regression suite covering your custom nodes, your model connections and your backup restore before each merge. Keep the fork's diff small and documented so that each rebase is a reviewable change rather than a rewrite.
Official Dify sources for source deployment
Before you change anything in a source deployment, read the local source code start guide in the Dify docs. It describes how to run the API, worker and web services from the repository while the middleware stack runs in Docker, and it is the reference your build sequence should follow. Pair it with the environment variable reference, which lists the EXPOSE_SSRF_PROXY_PORT and EXPOSE_SANDBOX_PORT settings that publish the proxy and sandbox ports on the host. Confirm each variable name against the version you intend to run, because defaults and names change between releases.
Next, read the Dify LICENSE file in the langgenius/dify repository before you modify the code. The Dify Open Source License is a modified Apache License 2.0 that restricts operating the source as a multi-tenant environment without written authorization and prohibits removing or changing the logo and copyright information in the console. Have legal review those terms against your planned customization, especially if you intend to offer the platform to other business units or customers as separate workspaces.
Finally, use the GitHub releases page to track each target version. Minor releases arrive roughly monthly, so plan a standing review of the release notes. The upgrade guide for each target version is published on that same releases page, and the Docker Compose documentation advises a backup before every upgrade and a check of .env.example for new variables. A forked source tree must go through the same steps and also merge your changes into each new release, so record which upstream version your fork is based on.
How DeployOpen works on this
DeployOpen plans, builds, documents and supports self-hosted open-source platforms inside your own infrastructure, including Dify source code deployments. For a source-based Dify build, we start by deciding which changes truly need a fork and which can live in configuration, plugins or custom tools, then carry that decision through the build, the upgrade plan and the handover.
How we scope
- We list each requested platform change and classify it as configuration, plugin, custom tool or fork-level code change.
- The written scope names the Dify version, the source branch or tag, and the middleware services that run in Docker.
- We record which published host ports are opened for the SSRF proxy and sandbox, and who may reach them.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- We set up the API, worker and web services from source, with PostgreSQL, Redis, Weaviate and storage in Docker.
- We keep customizations in a tracked branch with a documented diff against the upstream release tag.
- We test the built services against the security settings for SECRET_KEY, outbound proxy rules and sandbox isolation.
- We confirm the behavior of customized workflows, app import and export, and knowledge base indexing before sign-off.
How we hand over
- You receive the source repository, build steps, environment file layout and a written list of every fork-level change.
- Runbooks cover restarts, backups before upgrades, and how to check .env.example for new variables after a change.
- We document the upgrade procedure for each new minor release, since the upstream project ships roughly monthly.
- Your team is walked through the rebase process and the test suite that must pass before any upgrade is accepted.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped in writing.
- A retainer can cover rebasing the fork onto each upstream release and rerunning the customization tests.
- Security testing of the deployed application, APIs and agents can be scoped alongside the support work.
- Ask any provider to confirm who owns the fork, who reviews upstream security changes, and who approves production upgrades.
