Dify 설치 FAQ

설치하다 보면 자주 부딪히는 질문들을 정리했어요. 배포 방식별로 나눠서 볼게요.

배포 방법 (Deployment Methods)

이전 버전 설치 (Install Older Version)

특정 버전을 설치하려면 --branch 플래그를 쓰면 됩니다.

git clone https://github.com/langgenius/dify.git --branch 0.15.3

나머지 설정은 최신 버전을 설치할 때와 동일해요.

ZIP 아카이브로 설치 (Install Using ZIP Archive)

네트워크가 제한된 환경이나 git을 쓸 수 없을 때는 이렇게 해요.

# 최신 릴리스 다운로드
wget -O dify.zip "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r '.zipball_url')"
unzip dify.zip && rm dify.zip

아니면 ZIP을 다른 기기에서 다운로드하고 수동으로 옮겨도 돼요. 업그레이드하는 경우:

wget -O dify-latest.zip "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r '.zipball_url')"
unzip dify-latest.zip && rm dify-latest.zip
rsync -a dify-latest/ dify/
rm -rf dify-latest/
cd dify/docker
docker compose pull
docker compose up -d

클론이 "Remote branch null not found"로 실패할 때

Docker Compose로 Dify 배포의 클론 명령은 GitHub API를 통해 최신 Dify 버전을 알아내요. 그 요청이 실패하면(보통 미인증 요청의 GitHub 속도 제한 때문), jq가 null을 출력하고 git이 fatal: Remote branch null not found in upstream origin을 뱉습니다. 이럴 때는 명시적 버전으로 클론하세요. Dify releases에서 최신 버전 번호를 찾은 뒤 다음을 실행합니다.

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

--branch 없이 클론해도 동작해요. main의 Compose 파일은 최신 릴리스 이미지를 고정하므로, 릴리스 빌드를 실행하기는 하지만 배포 파일들(Compose 파일과 환경 템플릿) 자체는 개발을 따라가 태그된 릴리스와 어긋날 수 있어요.

백업 절차 (Backup Procedures)

업그레이드 전 백업 만들기 (Create Backup Before Upgrading)

데이터 손실을 막으려면 업그레이드 전에 항상 백업하세요.

cp -r dify "dify.bak.$(date +%Y%m%d%H%M%S)"

이 명령은 타임스탬프가 붙은 백업을 만들어 쉽게 복원할 수 있게 해줘요.

리버스 프록시 설정 (Reverse Proxy Setup)

프론트·백엔드 서브도메인 분리 시 로그인 세션이 끊길 때

리버스 프록시 뒤에서 웹과 API를 서브도메인으로 분리했다고 해볼게요(예: UI는 app.example.com, 백엔드는 api.example.com). 이런 경우 인증 쿠키가 두 호스트에 모두 닿을 수 없어요. 로그인은 성공한 것처럼 보이지만, 다음 요청에서 세션은 끊겨버리죠. .env에서 두 변수를 모두 설정한 뒤 Dify를 재시작하세요.

COOKIE_DOMAIN: 공유되는 최상위 도메인(예: example.com)으로 설정. 앞의 점은 선택사항이에요.
NEXT_PUBLIC_COOKIE_DOMAIN: 프론트엔드에서 크로스 서브도메인 쿠키를 활성화하려면 1로 설정.

docker compose down
docker compose up -d

쿠키는 최상위 도메인을 넘을 수 없어요. 그러니 프론트엔드와 백엔드는 같은 등록 가능한 도메인을 공유해야 합니다. 자세한 내용은 환경 변수를 참고하세요.