Step 1: Install Necessary Tools and Dependencies
1.1 Install Homebrew
Homebrew is the package manager for macOS, and we will use it to install the required tools. If you have already installed it, you can skip this step.
Open the terminal and execute:
/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)”
Due to network issues in China, downloading packages with Homebrew may be slow. You can configure a domestic mirror:
# Set brew.git mirror
git -C “$(brew –repo)” remote set-url origin https://mirrors.ustc.edu.cn/brew.git
# Set homebrew-core.git mirror
git -C “$(brew –repo homebrew/core)” remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git
# Set homebrew-cask.git mirror (if you need to use cask)
git -C “$(brew –repo homebrew/cask)” remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git
Next, we need to configure the Homebrew Bottles mirror, which is the source for precompiled binary packages. Choose the appropriate configuration method based on your shell type:
If you are using zsh (the default shell for macOS Catalina and later):
echo ‘export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles’ >> ~/.zshrc
source ~/.zshrc
1.2 Install Python and Node.js
macOS comes with Python pre-installed, but we will use brew to install it to ensure that Python is the latest version and the runtime environment is isolated.
Install Python 3 and Node.js 18:
brew install [email protected] node@18
Use the which command to verify if the installation was successful:
which python3
which node
If you see output paths like the following:
python3: /opt/homebrew/bin/python3 or /usr/local/bin/python3
node: /opt/homebrew/bin/node or /usr/local/bin/node
Then these commands are available for use.
If they are not available, manually configure the environment variables:
echo ‘export PATH=”/opt/homebrew/opt/[email protected]/bin:$PATH”‘ >> ~/.zshrc
echo ‘export PATH=”/opt/homebrew/opt/node@18/bin:$PATH”‘ >> ~/.zshrc
source ~/.zshrc
Install the Python package management tool
brew install poetry
1.3 Install PostgreSQL
PostgreSQL is the most popular open-source database system and is the main database for Dify.
brew install postgresql@14
brew services start postgresql@14
1.4 Install Redis
Redis is a high-speed caching system that Dify uses for data caching to accelerate data retrieval.
brew install redis
brew services start redis
Step 2: Configure PostgreSQL
2.1 Create Database and User
psql postgres
Execute the following in the PostgreSQL command line:
CREATE DATABASE dify;
CREATE USER dify WITH PASSWORD ‘difyai123456’;
GRANT ALL PRIVILEGES ON DATABASE dify TO dify;
\q
The command GRANT ALL PRIVILEGES ON DATABASE dify TO dify; means that the user dify has full permissions on the database dify.
Step 3: Install and Configure Dify
3.1 Clone the Repository
git clone https://github.com/langgenius/dify.git
cd dify
3.2 Configure the Backend
cd api
# Create an isolated Python environment
python3 -m venv venv
source venv/bin/activate
# Copy the environment configuration file
cp .env.example .env
# Generate a random key and replace the value of SECRET_KEY in .env
awk -v key=”$(openssl rand -base64 42)” ‘/^SECRET_KEY=/ {sub(/=.*/, “=” key)} 1’ .env > temp_env && mv temp_env .env
poetry install
Use a text editor (like VS Code or nano) to edit the .env file and add the database and Redis configurations:
# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=dify
DB_PASSWORD=difyai123456
DB_DATABASE=dify
# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_USERNAME=
REDIS_PASSWORD=difyai123456
REDIS_USE_SSL=false
REDIS_DB=0
3.3 Configure the Frontend
cd ../web
# Install frontend application dependencies
npm install
# Copy the environment configuration file
cp .env.example .env
Step 4: Start the Services
4.1 Start the Backend Service
In the api directory:
# Activate the Python virtual environment
source venv/bin/activate
# This is a database migration command that uses Flask-Migrate (the database migration tool used by Dify) to update the database structure
python manager.py db upgrade
# Run Dify’s backend server
python manager.py run
poetry shell
flask db upgrade
4.2 Start the Frontend Service
In a new terminal window, navigate to the web directory:
# Start the frontend service
npm run dev
Step 5: Configure Local Access
5.1 Install and Configure Nginx
brew install nginx
# Create Nginx configuration file
mkdir -p /opt/homebrew/etc/nginx/sites-enabled
nano /opt/homebrew/etc/nginx/sites-enabled/dify.conf
Add the following configuration:
Define a local server on port 8080, while proxying the Dify frontend (port 3000) and backend (port 5001) applications
server {
listen 8080;
server_name localhost;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection ‘upgrade’;
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
location /api {
proxy_pass http://localhost:5001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection ‘upgrade’;
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
The lines proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection ‘upgrade’; support WebSocket connections, enabling real-time communication.
proxy_set_header Host $host; passes the original request’s hostname to the backend server, ensuring that the backend server can correctly handle the request.
proxy_cache_bypass $http_upgrade; bypasses the cache when handling WebSocket connections, ensuring the correctness of real-time communication.
Start Nginx:
brew services start nginx
1.Open your browser and visit http://localhost:8080
2.You should see the Dify login interface
Step 6: Create a Startup Script
Your computer may restart, and starting the services manually each time can be cumbersome, so you can create a startup script for one-click startup of the Dify services.
6.1 Create the Startup Script
Create a startup script in the project root directory:
nano ~/start-dify.sh
Add the following content:
#!/bin/bash
# Start PostgreSQL
brew services start postgresql@14
# Start Redis
brew services start redis
# Start Nginx
brew services start nginx
# Start Backend
cd ~/path/to/dify/api
source venv/bin/activate
python manager.py run &
# Start Frontend
cd ~/path/to/dify/web
npm run dev &
echo “Dify services have started”
~/path/to/ should be adjusted according to your actual installation directory
Set script permissions:
chmod +x ~/start-dify.sh
Troubleshooting Common Issues
Port Occupation Issues
If you encounter port occupation:
# Check port occupation
lsof -i :3000
lsof -i :5001
lsof -i :8080
# Terminate the process
kill -9
Permission Issues
# Change project directory permissions
chmod -R 755 ~/path/to/dify
Database Connection Issues
# Check PostgreSQL status
brew services list
# Restart PostgreSQL
brew services restart postgresql@14