Skip to main content
The default Docker Compose deployment runs Dify with bundled PostgreSQL, Weaviate, and the other services it needs, so you don’t set up a database or vector store first.

​
Before Deployment

​
Hardware

  • CPU: at least 2 cores
  • RAM: at least 4 GiB

​
Software

Install Docker with Docker Compose 2.35.0 or later, and make sure the Docker daemon is running. You also need Git to download Dify, and OpenSSL to generate a token for the agent’s local sandbox. Check the Compose version before starting:

​
Deploy and Start

For an existing deployment, follow Upgrade instead to keep its configuration and data.
1

Get a Dify Release

Choose a version from Dify releases and clone it, replacing <version> with its tag:
2

Configure Startup Settings

Create the configuration file from its template:
Generate a token for the agent’s local sandbox:
In .env, set DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN to the output. The agent backend and its local sandbox require this shared token to start.
Before the first start:
  • For production, set the credentials in Secure the Deployment.
  • To use another bundled vector store or MySQL instead of Weaviate and PostgreSQL, set it in .env. Switching after the first start doesn’t move existing data. See VECTOR_STORE and Database Configuration for the settings each needs.
3

Start and Check the Services

From dify/docker, run:
Long-running services should show Up or healthy. The init_permissions task runs once to prepare storage permissions and shows Exited (0) when it’s done.

​
Access

Open http://localhost/install in your browser and create the administrator account, then sign in at http://localhost. For a remote deployment, replace localhost with the server’s IP address or domain. The default HTTP port is 80. If port 80 is in use, set EXPOSE_NGINX_PORT in docker/.env to another port, and add that port to the address.
For real-time collaboration on a remote server, add NEXT_PUBLIC_SOCKET_URL to docker/.env with the server’s WebSocket address, then run docker compose up -d.

​
Customize

Put deployment-wide settings in docker/.env: Compose profiles, published ports, mount paths, health-check scheduling, and the shared credentials in Secure the Deployment. Other settings belong to a service. Most services load their bundled .defaults files under docker/envs/; leave those as they are and put your changes in the local .env file named in their comments. Settings shared by the API, workers, and scheduled tasks go in envs/core-services/api-worker.env. For example, to raise Nginx’s maximum request body size to 200M, run these from dify/docker:
1

Set the Override

If envs/infrastructure/nginx.env doesn’t exist, create it:
In envs/infrastructure/nginx.env, set:
2

Apply the Change

Validate the configuration and recreate the affected containers:
Use up -d, not docker compose restart: restart keeps the containers’ old environment.
3

Check the Active Value

Read Nginx’s active configuration:
The output should include client_max_body_size 200M;. If it shows another value, check docker/.env for an override, then see Precedence for the other places a value can come from.
For every variable and the full precedence rules, see Environment Variables.

​
Secure the Deployment

Before others can reach the deployment, configure HTTPS and replace the bundled development credentials in docker/.env: If Dify is already running, apply the new values with docker compose up -d. The database password is the exception: once the database is initialized, change the password on the database server first, then update DB_PASSWORD to match.
Leave SECRET_KEY as it is: unless you set one, Dify generates a random key on first start and stores it with its data. Setting or changing it later stops tokens and file links signed with the old key from working; see SECRET_KEY for everything it affects.
The default stack publishes no host ports for the database, Redis, Code sandbox, or Weaviate. Restrict access to them on the private network too.

​
Upgrade

Choose the target release on Dify releases and read its upgrade guide first. Run every Compose command below with the deployment’s existing project name and files, including any -p, -f, or COMPOSE_PROJECT_NAME, so its named volumes stay attached.
1

Back Up the Deployment

  1. From dify/docker, stop the deployment so the databases aren’t writing while you copy their files:
    If you can’t stop it, back up the databases with their own dump tools instead.
  2. Back up docker/.env, your local service .env files, any custom Compose files, and persistent data, including docker/volumes/ and any external databases and storage.
  3. If your deployment includes local_sandbox, also back up its named volumes, mounted at /home/dify and /workspace. Their names carry the Compose project prefix; list them with:
  4. Save the output of docker compose config to compare after the update. It contains secrets, so keep it private.
2

Update to the New Release

Git doesn’t track your local .env files or the data in docker/volumes/, so checking out a release leaves them in place. If you edited tracked files such as docker-compose.yaml, stash those edits first. From the repository root:
Then reapply your edits to the new release’s files, for example with git stash pop, and resolve any conflicts.
3

Review Your Configuration

Compare docker/.env.example with your docker/.env, and each local service file with its .defaults or .env.example template.Update your existing files with the settings you need; copying a template over them discards your overrides. If a setting has a new name in the template, use the new name. Leave the lines under Container variable mappings unchanged.Keep the existing database and every vector store your knowledge bases still use, with their connection settings and Compose profiles. Changing DB_TYPE or VECTOR_STORE doesn’t migrate data.Finally, compare the new docker compose config output with the copy you saved: check credentials, volume paths, profiles, and the settings you customized.
4

Apply and Check the Upgrade

From dify/docker, run:
Long-running services should show Up or healthy, and init_permissions should show Exited (0). Then open Dify and try the features that use your custom settings.
Last modified on November 4, 2026