Prerequisites

• Operating System: Windows 10/11, macOS 10.14 or later, Linux (Ubuntu 20.04 or later recommended)
• Specifications: CPU 2 cores or more, RAM 4GB or more, Disk space 20GB or more
• Tools: Docker Desktop (supports all OS), Git (command-line tool)

1. Installing Docker

For Windows

1. Download Docker Desktop:

   • Download "Docker Desktop for Windows" from the Docker official website.
   • Run the installer and follow the on-screen instructions.
   • Important: It is recommended to enable WSL 2. Select "Use WSL 2 instead of Hyper-V" during installation.

2. Verify Installation:

   • Launch "Docker Desktop" from the Start Menu. If the tray icon appears, it's successful.
   • Run docker --version in Command Prompt. If version information is displayed, it's OK.

For macOS

1. Download Docker Desktop:

   • Download "Docker Desktop for Mac" from the Docker official website.
   • Open the DMG file and drag the Docker icon to the "Applications" folder.

2. Verify Installation:

   • Launch Docker Desktop from the Applications folder. If the tray icon appears, it's successful.
   • Run docker --version in Terminal. If version information is displayed, it's OK.

For Linux (Ubuntu example)

1. Install Docker:

   sudo apt update
   sudo apt install docker.io -y
   sudo systemctl enable --now docker
   sudo usermod -aG docker $USER

2. Verify Installation:

   • Run docker --version in Terminal. If version information is displayed, it's OK.
   • Log out and log back in to ensure the user is added to the docker group.

2. Installing Dify

Steps

1. Install Git (if not already installed):

   • Windows/macOS: Download and run the installer from the Git official website.
   • Linux: Run sudo apt install git -y in Terminal.

2. Get the Dify source code:

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

3. Configure environment variables (optional):

   cp .env.example .env
   nano .env  # Edit environment variables with a text editor

4. Start Dify with Docker Compose:

   docker compose up -d

   • Note: Use docker compose for Docker Compose v2, and docker-compose for v1.

5. Verify Operation:

   • Access http://localhost in your browser. If the Dify initialization screen appears, it's successful.
   • Create an administrator account on the initialization screen (set email address, username, password).

3. Common Issues and Solutions

1. Docker Compose not found

• Cause: Docker Compose may not be installed.
• Solution:
  • Windows/macOS: Reinstall Docker Desktop and ensure "Docker Compose" is enabled.
  • Linux: Run the following commands in Terminal:

    sudo curl -L "https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
    sudo chmod +x /usr/local/bin/docker-compose

2. Port conflicts

• Cause: Ports used by Dify (e.g., 80, 443, 5001) may be occupied by other services.
• Solution:
  • Change NGINX_HTTP_PORT and NGINX_HTTPS_PORT in the .env file to other ports (e.g., 8080 → 8081).
  • After changes, run docker compose down and then docker compose up -d.

3. Data not saving

• Cause: Docker volumes may not be configured correctly.
• Solution:
  • Stop services with docker compose down.
  • Check volumes with docker volume ls and remove unnecessary volumes with docker volume rm <volume_name>.
  • Restart with docker compose up -d.

4. Additional Information

1. Basic Docker Compose Commands

• Start services: docker compose up -d
• Stop services: docker compose down
• Check container status: docker compose ps
• View logs: docker compose logs -f

2. How to Add Models

1. Log in to the Dify admin panel.
2. Select "Model Providers" from the left-side menu.
3. Click the "Add Model" button and enter the API key for the model you want to use (e.g., OpenAI, Google Gemini).

3. Support and Updates

• Official Documentation: Dify Official Website
• Community: GitHub, Discord
• Update Method: In the source code directory, run git pull and then restart with docker compose up -d.

This is the installation guide for Dify. If you encounter any issues with the steps, please consult the community or official support. Even if you are new to Docker, you should be able to get it working by following the instructions carefully.