Dify 스터디에 참여하며, dify를 추가 요금 없이 사용할 수 있도록 로컬 설치가 가능하다는 것을 알게 되었습니다.하여 아무것도 모르는 상태로 dify 설치를 시도해봤습니다.
진행과정
ChatGPT에게 Dify 로컬 설치 방법을 물어봤습니다.
도커 이외에 몇 가지 방법을 알려줬는데,
도커에 대한 안 좋은 기억이 있어서 굳이 '복잡한 방법'을 알려달라고 했습니다.
그래서 어떻게 해야되냐?
위에서 ChatGPT가 알려준 방식을 복사해서 md 파일로 만들었습니다.
클로드코드를 켠 후, 이 md 파일을 읽고 dify 설치를 해달라고 합니다.
그리고 대화창에서 권한 요청할 때 마다 딸깍딸깍 -> 설치완료 ㅎㅎㅎㅎ (끗) 참 쉽죠?
그리고 클로드코드에게 - 오늘 니가 dify 설치한 과정을 블로그글로 요약해달라고 했습니다.
클로드코드가 없어도 아래 과정으로 설치하실 수 있습니다. :)
# Dify 로컬 설치 가이드: 도커 없이 macOS에서 완전 설치하기
> Dify를 도커 없이 macOS 환경에서 완전히 로컬 설치하는 방법을 단계별로 설명합니다.
## 목차
1. [개요](#개요)
2. [사전 요구사항](#사전-요구사항)
3. [1단계: 필수 도구 설치](#1단계-필수-도구-설치)
4. [2단계: Qdrant 벡터DB 설치](#2단계-qdrant-벡터db-설치)
5. [3단계: PostgreSQL 설정](#3단계-postgresql-설정)
6. [4단계: Dify 소스코드 및 환경 설정](#4단계-dify-소스코드-및-환경-설정)
7. [5단계: API 서버 실행](#5단계-api-서버-실행)
8. [6단계: 웹 프론트엔드 실행](#6단계-웹-프론트엔드-실행)
9. [문제 해결](#문제-해결)
10. [최종 확인](#최종-확인)
## 개요
Dify는 LLM 애플리케이션 개발을 위한 오픈소스 플랫폼입니다. 이 가이드는 도커 없이 macOS에서 Dify를 완전히 로컬 환경에 설치하는 방법을 다룹니다.
### 설치 후 사용 가능한 서비스
- **API 서버**: http://localhost:5001 (기본 포트, 충돌 시 다른 포트 사용)
- **웹 인터페이스**: http://localhost:3000
- **Qdrant 벡터DB**: http://localhost:6333
- **PostgreSQL**: localhost:5432
- **Redis**: localhost:6379
## 사전 요구사항
- macOS (이 가이드는 macOS Sequoia 24.6.0 기준)
- Homebrew 설치
- 기본적인 터미널 사용법
## 1단계: 필수 도구 설치
### 1.1 Python 3.12 설치
```bash
brew install [email protected]
```
### 1.2 Poetry 설치
```bash
curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
```
### 1.3 Node.js 및 pnpm 설치
```bash
# Node.js는 이미 설치되어 있을 수 있습니다
node --version # 확인
# pnpm 설치
npm i -g pnpm
```
### 1.4 PostgreSQL과 Redis 설치
```bash
# PostgreSQL과 Redis 설치
brew install postgresql@15 redis
# PATH 설정
export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"
echo 'export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"' >> ~/.zshrc
# 서비스 시작
brew services start postgresql@15
brew services start redis
```
### 1.5 기타 필요한 도구
```bash
brew install libmagic
```
## 2단계: Qdrant 벡터DB 설치
Qdrant는 Dify의 지식베이스 기능을 위한 벡터 데이터베이스입니다.
```bash
# Qdrant 바이너리 다운로드
curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-apple-darwin.tar.gz -o qdrant.tar.gz
# 압축 해제
tar -xzf qdrant.tar.gz
# 백그라운드 실행
./qdrant &
```
실행 확인:
```bash
curl http://localhost:6333/
# {"title":"qdrant - vector search engine","version":"1.15.4",...} 응답이 나오면 성공
```
## 3단계: PostgreSQL 설정
### 3.1 데이터베이스 및 사용자 생성
```bash
# dify 데이터베이스 생성
createdb dify
# dify 사용자 생성 및 권한 부여
psql -d postgres -c "CREATE USER dify WITH PASSWORD 'difypass';"
psql -d postgres -c "GRANT ALL PRIVILEGES ON DATABASE dify TO dify;"
psql -d postgres -c "ALTER DATABASE dify OWNER TO dify;"
psql -d dify -c "GRANT CREATE ON SCHEMA public TO dify;"
```
## 4단계: Dify 소스코드 및 환경 설정
### 4.1 소스코드 다운로드
```bash
git clone https://github.com/langgenius/dify.git
cd dify
```
### 4.2 API 서버 환경 설정
```bash
cd api
# 환경 파일 복사
cp .env.example .env
# 강한 SECRET_KEY 생성
python3 -c "import secrets,base64; print('SECRET_KEY='+base64.b64encode(secrets.token_bytes(42)).decode())"
```
### 4.3 .env 파일 수정
`.env` 파일을 열어서 다음 설정들을 수정합니다:
```bash
# SECRET_KEY (위에서 생성한 키로 교체)
SECRET_KEY=생성된키값
# Database 설정
DB_USERNAME=dify
DB_PASSWORD=difypass
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=dify
# Redis 설정 (비밀번호 제거)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_USERNAME=
REDIS_PASSWORD=
CELERY_BROKER_URL=redis://localhost:6379/1
# 벡터 스토어 설정
VECTOR_STORE=qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=
# 로컬 파일 저장 설정
STORAGE_TYPE=opendal
OPENDAL_SCHEME=fs
OPENDAL_FS_ROOT=storage
# API URLs (기본 포트 5001, 충돌 시 다른 포트 사용)
CONSOLE_API_URL=http://localhost:5001
SERVICE_API_URL=http://localhost:5001
FILES_URL=http://localhost:5001
INTERNAL_FILES_URL=http://127.0.0.1:5001
# Plugin 설정 (포트 충돌 시 다른 포트 사용)
PLUGIN_DAEMON_URL=http://127.0.0.1:5002
```
### 4.4 Python 의존성 설치
```bash
# Python 환경 설정
poetry env use python3.12
poetry install
# 누락된 패키지 설치
poetry add cloudscraper opendal
```
### 4.5 데이터베이스 마이그레이션
```bash
poetry run flask db upgrade
```
## 5단계: API 서버 실행
### 5.1 API 서버 시작
```bash
poetry run flask run --host 0.0.0.0 --port 5001 --debug &
```
### 5.2 Celery 워커 시작
새 터미널을 열어서:
```bash
cd dify/api
export PATH="$HOME/.local/bin:$PATH"
export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"
# Celery 워커 실행
poetry run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace &
```
### 5.3 API 서버 확인
```bash
curl http://localhost:5001/console/api/setup
# {"step": "not_started"} 또는 {"step": "finished"} 응답이 나와야 합니다
```
## 6단계: 웹 프론트엔드 실행
### 6.1 의존성 설치
```bash
cd ../web
pnpm install
```
### 6.2 환경 설정
```bash
cp .env.example .env.local
```
`.env.local` 파일에서 API URL을 수정합니다:
```bash
NEXT_PUBLIC_DEPLOY_ENV=DEVELOPMENT
NEXT_PUBLIC_EDITION=SELF_HOSTED
NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api
```
### 6.3 빌드 및 실행
```bash
# 프로덕션 빌드
pnpm build
# 서버 시작
pnpm start &
```
## 문제 해결
### 포트 충돌 문제
다른 서비스가 기본 포트를 사용하고 있다면 다음 방법들로 해결하세요:
**방법 1: 사용 중인 프로세스 종료**
```bash
# 포트 사용 확인
lsof -ti:5001
# 포트 사용 프로세스 종료 (주의: 중요한 서비스일 수 있음)
lsof -ti:5001 | xargs kill -9
```
**방법 2: 다른 포트 사용 (권장)**
```bash
# API 서버를 다른 포트로 실행
poetry run flask run --host 0.0.0.0 --port 5007 --debug &
# .env 파일도 함께 수정
CONSOLE_API_URL=http://localhost:5007
SERVICE_API_URL=http://localhost:5007
FILES_URL=http://localhost:5007
INTERNAL_FILES_URL=http://127.0.0.1:5007
# 웹 .env.local 파일도 수정
NEXT_PUBLIC_API_PREFIX=http://localhost:5007/console/api
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5007/api
```
### Plugin daemon 에러
API 로그에서 plugin daemon 관련 에러가 발생하면 `.env`에서 `PLUGIN_DAEMON_URL`을 사용하지 않는 포트로 변경하세요.
### 권한 에러
PostgreSQL 권한 에러 발생 시:
```bash
psql -d dify -c "GRANT CREATE ON SCHEMA public TO dify;"
psql -d postgres -c "ALTER DATABASE dify OWNER TO dify;"
```
### 의존성 에러
특정 Python 패키지가 없다는 에러가 나오면:
```bash
poetry add 패키지명
```
## 최종 확인
모든 서비스가 정상적으로 실행되었다면:
1. **웹 브라우저**에서 `http://localhost:3000` 접속
2. **초기 설정** 화면에서 관리자 계정 생성
3. **Dify 플랫폼** 사용 시작!
### 실행 중인 서비스 목록
| 서비스 | URL/포트 | 용도 |
|--------|----------|------|
| Dify Web | http://localhost:3000 | 웹 인터페이스 |
| Dify API | http://localhost:5001 | 백엔드 API |
| Qdrant | http://localhost:6333 | 벡터 데이터베이스 |
| PostgreSQL | localhost:5432 | 메인 데이터베이스 |
| Redis | localhost:6379 | 캐시 및 메시지 큐 |
### 서비스 상태 확인 명령어
```bash
# API 서버 상태
curl http://localhost:5006/console/api/setup
# Qdrant 상태
curl http://localhost:6333/
# 웹 서버 상태
curl -I http://localhost:3000/
```
## 마무리
축하합니다! 이제 Dify가 완전히 로컬 환경에서 실행되고 있습니다.
### 다음 단계
1. AI 모델 제공업체 설정 (OpenAI, Claude 등)
2. 첫 번째 AI 애플리케이션 생성
3. 지식베이스 구축 및 RAG 파이프라인 설정
### 유용한 팁
- 개발 중에는 `--debug` 옵션으로 실행하여 자세한 로그 확인
- `.env` 파일의 설정들을 프로젝트 요구사항에 맞게 조정
- 정기적으로 `git pull`로 최신 버전으로 업데이트
이 가이드가 도움이 되었다면, Dify 커뮤니티에 기여해보세요! 🚀
---
**작성일**: 2025년 9월 6일
**테스트 환경**: macOS Sequoia 24.6.0, Dify v1.8.1
**문의사항**: GitHub Issues 또는 Dify 커뮤니티