How to Install Dify Locally With Docker Compose

Tool overview

Dify is an open-source platform for building LLM apps, chatbots, RAG workflows, agents, and internal AI tools through a visual interface. It is useful when you want more structure than a simple chat UI but do not want to build every prompt chain, retrieval step, and model connection from scratch.

Local Dify makes sense if you want to prototype privately, connect local models, test workflows before hosting them, or learn how the platform works without depending on a managed cloud setup.

Step-by-step setup

docker compose version

Step 1: Clone Dify

Use the current release branch:

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

If your shell does not have jq, clone the repository normally and check the Dify releases page before choosing a version:

git clone https://github.com/langgenius/dify.git

For a local test machine, the normal repository clone is fine. For anything you depend on, pin a release instead of running an unknown moving branch.

Step 2: Prepare the Docker environment file

Move into the Docker directory:

cd dify/docker

Copy the example environment file:

cp .env.example .env

For a first local install, do not edit a long list of settings immediately. Start the default stack first, confirm the UI works, and only then change storage, domain, worker, or provider settings.

Step 3: Start Dify

Start the stack:

docker compose up -d

Check the containers:

docker compose ps

Dify starts several services, including the API, worker, web frontend, plugin daemon, Postgres, Redis, Weaviate, Nginx, sandbox, and proxy components. Some services may take a short time to become healthy on the first run.

When the stack is ready, open the installer:

http://localhost/install

Create the first admin account, then log in at:

http://localhost

Step 4: Connect Dify to Ollama

First confirm Ollama works on the host:

ollama pull llama3.2
ollama list
curl http://localhost:11434/api/tags

Inside Dify, go to the model provider settings and add Ollama. Use the model name exactly as shown by ollama list.

For Docker Desktop on Windows or macOS, use this base URL:

http://host.docker.internal:11434

For Linux, host.docker.internal may not resolve unless you add a host gateway mapping. If it does not work, use the host machine IP that the container can reach, or add this style of mapping to the relevant Dify services:

extra_hosts:
  - "host.docker.internal:host-gateway"

Then try the same base URL again:

http://host.docker.internal:11434

Step 5: Make Ollama reachable from containers

If Dify cannot reach Ollama, the issue is usually not the model. It is the network boundary between a Docker container and the host.

Test from the host first:

curl http://localhost:11434/api/tags

Then test from a temporary container:

docker run --rm curlimages/curl:latest http://host.docker.internal:11434/api/tags

If the container cannot reach Ollama, check how Ollama is bound on your system. On Linux, Ollama may only be listening on localhost. For a private local machine, you can bind Ollama to an address reachable from Docker, then restrict exposure with firewall rules. Do not expose Ollama to the public internet.

Step 6: Build your first local workflow

After the model provider connects:

1. Create a new Dify app.
2. Choose a chatflow or workflow app type.
3. Select your local Ollama model.
4. Add a simple system instruction.
5. Send a test message.
6. Add knowledge or retrieval only after the base chat works.

If you are testing RAG, start with one small document. Local embeddings, parsing, vector storage, and generation all consume resources. A small test makes it easier to see whether a failure is model-related, document-related, or infrastructure-related.

Persistence and backups

Dify data is stored by the Docker stack in its configured volumes and service data directories. Do not delete volumes casually. Before upgrades, back up the project directory and the Docker volumes that hold database and vector data.

For routine local use:

• Keep your dify/docker/.env file.
• Keep Docker volumes.
• Avoid docker compose down -v unless you intentionally want to remove local data.
• Export important apps from the UI before major upgrades.
• Read the release notes before changing versions.

Updating Dify

Upgrade steps can vary by release. For a local system, use a cautious update flow:

cd dify
git fetch --tags

Then check the release notes for the version you want. After updating the code, compare .env.example against your existing .env, apply needed changes, and restart:

cd docker
docker compose down
docker compose up -d

Do not update a working local Dify instance without a backup if it contains workflows you care about.

Common problems

The installer does not open

Run:

docker compose ps
docker compose logs nginx
docker compose logs api

If Nginx is not running or port 80 is already used, change the exposed port in the Docker configuration or stop the conflicting service.

Dify cannot see Ollama models

Use http://host.docker.internal:11434 on Docker Desktop. On Linux, add a host gateway mapping or use a reachable host IP. Do not use http://localhost:11434 from inside Dify unless Ollama runs in the same container network under that address.

Containers keep restarting

Check available memory and disk space. Dify is not a single lightweight container; it runs several services. Local model inference on the same machine can make resource pressure worse.

Database errors appear after changing files

Restart cleanly:

docker compose down
docker compose up -d

If you changed environment files, compare them with the current examples and check release notes before deleting anything.

Security notes

Keep local Dify private by default. A self-hosted Dify instance can hold API keys, workflow logic, documents, and user data.

Use these rules:

• Do not expose http://localhost/install to a public network.
• Use strong admin credentials.
• Avoid putting secrets into shared screenshots.
• Keep model provider keys in environment settings, not in prompts.
• Do not expose Ollama publicly.
• Back up before upgrades.

Background, planning, and caveats

Approximate planning cost (U.S.)

For local Dify, cost is mostly hardware and operations:

• Hardware or VPS: Dify's own minimum is modest for entry use, but practical local stacks run better with extra RAM and stable disk I/O.
• Storage: vector collections, app metadata, uploaded documents, logs, and model caches grow over time.
• Optional cloud/VPS: a small virtual machine can replace a local laptop for 24/7 testing but increases recurring spend.
• API/model costs: hosted model providers and data services are usually metered, even when Dify is local.
• Optional managed hosting: Dify Cloud plans are helpful when you need predictable operations and less infrastructure overhead.

Use this rule:

• keep it local for private R&D and small pilots,
• consider managed hosting once availability, backups, and access controls become part of operations.

Cost breakdown

• one-time local setup: host capacity, storage allocation, optional SSL/domain setup.
• recurring local setup: power/internet and third-party API usage.
• managed option: workspace subscription and usage terms from current Dify pricing.

Data persistence and backups

Treat Dify's compose services as stateful:

• persist and version .env,
• keep container volumes for API, worker, vector, and database services,
• back up your dify/docker project files and related volumes before major upgrades.

Backups should include any knowledge document libraries that are hard to rebuild.

Credential handling

• Store provider/API keys in environment files or secret managers, not in apps or prompts.
• Revoke and rotate keys before moving from local test to any shared deployment.
• Use separate credentials per environment where possible.

Security risk and operational cautions

• Exposing local ports to external networks creates token exposure risk.
• Keep localhost/install and admin pages private while testing.
• Validate which external hosts are allowed in any model or retrieval flow.

Questions before installing

• What workflow volume and doc load are you supporting in the first quarter?
• Do you need guaranteed availability, or is intermittent local availability acceptable?
• Who owns the .env lifecycle and update approvals?
• Do you have a defined rollback path for vector and database state?

Red flags

• No clear test for backup restore.
• Enabling many network integrations before basic auth and model routing are locked down.
• Using local docs/knowledge base data without retention and retention rules.

Rollback and update guidance

For rollback:

• keep a known-good compose configuration and matching .env,
• stop services and restore the prior volumes for DB/vector layers,
• validate with one smoke test app before returning users.

For updates:

• follow release notes,
• compare .env.example and migrate values intentionally,
• restart services in a staging pass before a production cutover.

Bottom line

Install Dify with Docker Compose, open http://localhost/install, and connect local models only after the base stack is healthy. For Ollama, the key detail is the base URL: from inside Dify's containers, use a host-reachable address such as http://host.docker.internal:11434, not plain localhost.