Dify in Docker: installation, first-run setup and connecting models

Dify in Docker installs with four commands, but then the questions begin: what to check if the page will not open, how to create the administrator and where to put the model key. Below is installing Dify through Docker Compose following the official documentation, the first-run setup, and connecting models through an OpenAI-compatible gateway. Dify's versions and container set update over time, so if something differs from this text, follow the "Deploy Dify with Docker Compose" page in Dify's documentation (docs.dify.ai).

What you need before installing

The minimum requirements according to Dify's documentation:

• CPU: 2 cores or more;
• memory: 4 GiB or more;
• Docker Compose 2.24.0 or newer (check with docker compose version);
• on Linux, Docker 19.03+; on macOS and Windows, Docker Desktop (for macOS the documentation advises giving the Docker virtual machine at least 2 vCPUs and 8 GiB of memory; Windows needs WSL 2, and code and data are best kept in the Linux file system).

Cloning the repository requires git, and the command from the documentation also needs curl and jq. The source code and project description are in the repository github.com/langgenius/dify↗.

Dify in Docker: installation steps

1. Clone the repository

The command from the documentation fetches the latest release through the GitHub API:

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 it fails with fatal: Remote branch null not found in upstream origin, GitHub has most likely rate-limited unauthenticated requests and jq returned null. Specify the version explicitly, using the latest release number from the Releases page:

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

2. Prepare the configuration and start

cd dify/docker
cp .env.example .env
docker compose up -d

.env holds the essential startup values; optional provider settings are templates in docker/envs/. If you change settings, restart after editing: docker compose down, then docker compose up -d.

The first start downloads images and takes a few minutes. About fifteen containers start: the core services (api, worker, web, plugin_daemon and others), dependencies (db_postgres, redis, weaviate, nginx, sandbox, ssrf_proxy) and a one-time task init_permissions, which sets storage permissions and exits.

3. Check that everything is up

docker compose ps

Every container should have the status Up or healthy. An Exited status on init_permissions is normal.

4. Create the administrator

Open the initialization page:

• on your own machine: http://localhost/install;
• on a server: http://SERVER_IP/install.

Set up the administrator account, then sign in at the address without /install. The first user becomes the workspace owner. According to Dify's documentation, only the owner and admins manage model providers.

Connecting models through a gateway

In Dify, models are connected through providers. For any OpenAI-compatible API you use the OpenAI-API-compatible plugin. In brief, with per-field details in the article connecting Zukko to Dify↗:

1. In the Zukko dashboard↗ create a fetch_... key (shown once).
2. In Dify open Integrations → Model Provider, install the OpenAI-API-compatible plugin (from the Marketplace) and click Add Model. In older versions the path may differ: look for Model Provider in the workspace settings.
3. Set the model type LLM, a model name from GET https://api.zukko.pro/v1/models (for example claude-sonnet-5-5 or deepseek-v4.1-flash), the key, and API Base URL https://api.zukko.pro/v1 (with /v1, without /chat/completions).
4. Set the model's real context size: if you leave the default, Dify will assume the model accepts few tokens.
5. Save: Dify validates the data before making the model available.

Before that it helps to confirm that the server can reach the gateway at all. Run on the machine with Dify:

curl https://api.zukko.pro/v1/models \
  -H "Authorization: Bearer fetch_your_key"

If the model list arrives, the network is fine. Plugins are installed from the Marketplace, so the server needs internet access. Zukko's API documentation is in the chat completions↗ section.

Knowledge base embeddings need a separate provider: Zukko's catalog has no embedding models, only chat models.

A cost guide. Suppose one workflow run spends 3,000 input and 500 output tokens, and there are 1,000 runs. That is 3M input and 0.5M output. Prices as of October 18, 2026, input / output per 1M:

• glm-5.3-flash (0.04 / 0.04): 3 × $0.04 + 0.5 × $0.04 = $0.12 + $0.02 = $0.14;
• gpt-6.1-sol (0.27 / 1.32): 3 × $0.27 + 0.5 × $1.32 = $0.81 + $0.66 = $1.47;
• claude-sonnet-5-5 (0.4 / 2): 3 × $0.4 + 0.5 × $2 = $1.20 + $1.00 = $2.20.

Dify calls the model in the OpenAI format, so for Claude the cache gives no discount: all input is billed at the input price. The example is illustrative; see your own volumes in the dashboard's "Usage" section. Create a separate key with a daily and monthly limit for Dify in advance (see key limits↗).

Typical startup problems

Port 80 is taken. Stop the conflicting service (most often Nginx or Apache on the host) or change the port mapping in docker-compose.yaml, for example to "8080:80". After that Dify opens at http://localhost:8080.

502 Bad Gateway. Dify's documentation links this to Nginx forwarding to outdated container IPs (IPs change when containers restart). It advises getting the current IPs with docker inspect and restarting Nginx or reloading its configuration; details are in the Docker Issues section of Dify's documentation.

The page loads forever and the browser console shows CORS errors. Usually the domain or address was changed. Check the variables CONSOLE_API_URL, CONSOLE_WEB_URL, SERVICE_API_URL, APP_API_URL and APP_WEB_URL: they must match the address you use to open Dify.

Sign-in "succeeds" but the session drops. If the interface and API are split across subdomains behind a reverse proxy, you need COOKIE_DOMAIN (the shared top-level domain) and NEXT_PUBLIC_COOKIE_DOMAIN=1.

Containers did not come back after a reboot. Run docker compose down, then docker compose up -d and wait for healthy.

Dify cannot reach a service on the host. A container does not see the host at 127.0.0.1: use the machine's local network IP. This does not apply to a gateway on the internet.

Model errors after connecting (401, 402, 403 model_not_allowed_for_key, 404 model_not_found) are covered in the article 401, 402, model not found: connection errors↗.

Updating and security

Make a copy before updating: cp -r dify "dify.bak.$(date +%Y%m%d%H%M%S)". Update steps depend on the release and are described on the Releases page. After updating, compare each .env.example with your .env: new variables may have appeared, and new services in the Compose file.

If Dify is reachable from the internet, put HTTPS in front and restrict access: Dify stores provider keys, which give direct access to your balance. It is better to create a separate Zukko key with a daily limit.

FAQ

How many resources does Dify need?

The documentation's minimum is 2 CPU cores and 4 GiB of RAM. For a real load and a knowledge base you need more: go by monitoring on your own server.

Can I use Dify without Docker?

Yes, Dify's documentation describes running from source code, but Docker Compose is simpler to start with.

Which model should I add first?

Any inexpensive one will do to test the connection, for example deepseek-v4.1-flash or glm-5.3-flash. Choose for a production node after testing on 20 to 30 of your own examples.

Does this work with the cloud version of Dify?

Connecting a model through the same plugin and with the same fields is available in the cloud version too; Docker is only needed for your own server. What Dify is in general is explained separately in an overview article on the blog.

Once Dify is up, create a key on the API keys↗ page and add the first model.