Deploy Dify with Docker Compose

Tip

For common deployment questions, see FAQs.

Before Deployment#

Make sure your machine meets the following minimum system requirements.

Hardware#

CPU >= 2 Core
RAM >= 4 GiB

Software#

Operating System	Required Software	Notes
macOS 10.14 or later	Docker Desktop with Docker Compose 2.24.0+	Configure the Docker virtual machine with at least 2 virtual CPUs and 8 GiB of memory. For installation instructions, see Install Docker Desktop on Mac.
Linux distributions	Docker 19.03+ Docker Compose 2.24.0+	For installation instructions, see Install Docker Engine and Install Docker Compose.
Windows with WSL 2 enabled	Docker Desktop with Docker Compose 2.24.0+	Store source code and data bound to Linux containers in the Linux file system rather than Windows. For installation instructions, see Install Docker Desktop on Windows.

Deploy and Start#

Clone Dify

Clone the Dify source code to your local machine.

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git

Info

This command requires git, curl, and jq. If you see a command not found error, install the missing tool and run the command again.

When the clone fails with fatal: Remote branch null not found in upstream origin, retry with an explicit version, using the latest version number from Dify releases:

git clone --branch <version> https://github.com/langgenius/dify.git

See Clone Fails with “Remote branch null not found” for details.

Start Dify

Navigate to the docker directory in the Dify source code:
cd dify/docker
Copy the essential environment configuration file:
cp .env.example .env
To customize your deployment later, see Customize.
Start the containers:

Note
Dify requires Docker Compose 2.24.0 or later. Run docker compose version to confirm.
docker compose up -d
The following containers will be started:
- 7 core services: api, api_websocket, worker, worker_beat, web, plugin_daemon, agent_backend
- 8 dependent components: weaviate, db_postgres, redis, nginx, ssrf_proxy, agent_ssrf_proxy, sandbox, local_sandbox
- 1 one-time task: init_permissions, which sets storage file permissions and exits when done
Verify that all containers are running successfully:
docker compose ps
Each container should be in the Up or healthy status. An Exited status for init_permissions is expected.

Access#

Open the administrator initialization page to set up the admin account:

# Local environmenthttp://localhost/install# Server environmenthttp://your_server_ip/install

After completing the admin account setup, log in to Dify at:

# Local environmenthttp://localhost  # Server environmenthttp://your_server_ip

Customize#

To customize your deployment, edit environment variables in the relevant file, then restart Dify.

Edit Environment Variables

Essential startup values live in docker/.env, which you created from docker/.env.example during deployment. Edit them directly.
Optional or provider-specific settings have templates under docker/envs/. To override a default value, copy the matching template (drop the .example suffix), then edit your copy.

For example:
cd dify/dockercp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env

Values in docker/.env take precedence over values in any docker/envs/*.env files.

Tip

For descriptions of every variable, see Environment Variables.

Restart Dify

docker compose downdocker compose up -d

Upgrade#

Upgrade steps may vary between releases. Refer to the upgrade guide for your target version provided in the Releases page.

Note

After upgrading, compare each .env.example with its matching .env for new or changed variables.

If you’ve customized docker-compose.yaml, re-apply your changes onto the release’s new file rather than keeping the old one. A release can add services that Dify needs to run.