A. Docker 사용해서 설치하기
Dify(디파이) 노코드 AI구축 기초부터 실무 가이드
(1) Docker(도커)란?
Dify(디파이)는 클라우드버전과 로컬버전이 있습니다. 클라우드버전을 사용해도 큰 제약이 없이 학습하는 상황에서는 그 편리함에 빠질 수 있다고 생각합니다. 그렇지만 본격적으로 사용하려고 하면 Dify 클라우드 무료버전은 앱을 10개까지만 사용할 수 있는 등의 한계점이 있습니다. (물론 유료로 가입하면 이런 제약은 해결됩니다)
그래서 다른 선택지로서 로컬버전을 사용하는 것입니다. 로컬버전은 PC나 서버에 Dify를 다운로드 및 설치하여 사용하는 것입니다. 즉 로컬환경에서 Dify(디파이)를 실행할 수 있는 것입니다. 그것에 필요한 것이 Docker(도커)입니다. 예를 들어, 독자가 이사를 할 때 모든 전자제품, 가구, 생활용품을 박스에 포장하게 됩니다. 그 박스들이 그대로 이삿짐트럭에 싣여 새 집으로 운반됩니다. 새 집에서는 박스를 열고 내용물을 꺼내기만 하면 원래 생활 환경을 재현할 수 있습니다. Docker(도커)는 바로 그 이삿짐박스와 같은 역할을 합니다.
Dify(디파이)에 필요한 모든 소프트웨어, 설정, 의존성이 'Docker컨테이너'라는 박스안에 담겨 있습니다. 그리고 이 박스만 있으면 macOS이든, Windows이든 상관없이 동일하게 Dify(디파이)를 실행할 수 있습니다.
여기서 한가지 생각을 떠올리게 됩니다. 왜 로컬환경에서 Dify(디파이)를 구축할 필요가 있을까?라고 생각됩니다.
비용문제입니다. 클라우드 버전은 편리하지만, 유료버전으로 전환하면 매달 비용이 과금됩니다. 반면에 로컬환경의 경우 초기설정만 하면 무제한으로 사용할 수 있습니다.
커스터마이징 가능성입니다. 로컬환경에서는 Dify(디파이)의 설정을 자신의 마음대로 변경할 수 있습니다. 클라우드 버전에서는 어려운 상세 조정도 마음껏 할 수 있습니다. 이는 아파트입주할 때 붙박이장을 입주자 마음에 드는 것을 추가한 후 입주할 것인지 있는 그대로 아파트에 입주할 것인지에 대한 차이점이라고 봐도 좋습니다.
보안측면도 있습니다.기밀성이 높은 데이터를 다루는 경우, 로컬환경이라면 외부에 데이터를 전송할 필요가 없습니다.
네트워크 환경 의존도가 낮다는 것입니다. 로컬환경에 구축하면 많은 기능들을 오프라인에서도 사용할 수 있습니다. 단, 여기서 한가지 주의해야 할 점은 OpenAI API등 외부 AI서비스를 이용하는 기능은 여전이 인터넷 연결이 필요합니다. 완전한 오프라인 환경에서 사용하고 싶다면 로컬 환경에서 동작하는 LLM(예; DeepSeek, Llama 3, Gemma, Qwen 등)의 도입이라는 선택지가 있습니다. 다만, 모델 파라미터 크기에 따라 상당한 계산자원이 필요할 수 있다는 점을 기억하기 바랍니다.
① Linux 환경
현대 웹환경에서는 다양한 환경들이 존재합니다. (서버 및 미들웨어 등) 블로그를 만드는 Wordpress, 웹서버는 nginx, 데이터를 관리하는 MySQL, PostgreSQL등, 화면을 꾸며주는 Next.js, React등 이것들 대부분은 Linux라는 환경에서 실행됩니다. 그런데도 신기하게도 그것을 사용하는 개발자들은 Windows, macOS, Linux등 여러 환경을 사용합니다. 그런데 왜 개발자들은 원격지에 있어도 리눅스환경에서 실행되고 있는 것들을 관리할 수 있는 것일까요?
현재가 아닌 과거에는 Linux에 무엇인가를 설치하고 사용하는 것은 정말로 전문가가 아니면 힘든 작업이었습니다. 새로운 집으로 이사갈때마다 가구를 일일이 옮겨야 하고 전기, 수도를 다시 정비해야 하고, 처음부터 집을 짓듯이 살펴야하는 수고가 있었습니다. 또한 개발자는 이미 사용하던 집(실제 운영하던)에서 이사간 집에서도 똑같은 구성의 가구배치나 물건들을 배치해야 하지만 미세하게 달라져서 그것이 문제의 원인이 되기도 합니다.
그래서 가장 먼저 나온 것이 가상화 기술이란 아이디어였습니다. 이 가상화 기술만 있으면 Windows든, macOS든, Linux든 어떤 환경안에 리눅스환경을 구축할 수 있습니다. 단, 이 가상화 기술에는 약간 문제가 있었습니다. 너무 크기 무거웠던 것입니다. 많이 나열해서 사용하면 스토리지나 기타 리소스를 대량으로 소비하게 되었습니다. 그래서 그것보다 효율적인 방법이 필요하게 된 것입니다.
②편리한 이삿짐박스의 등장
그런 상황 속에서 2013년에 등장한 것이 바로 Docker(도커)입니다. dotCloud라는 회사에서 탄생하여 컨테이너 기술이라는 "경량의 가상화"를 제안한 것입니다. 이 경량의 가상화 박스는 기존의 가상화 기술과 비교했을 때 훨씬 더 가볍습니다. 필요한 기능만을 포함하기 때문에 상황에 따라 메모리 사용량이나 기동시간이 기존의 가상화기술에 비해 수분의 일에 불과해질 수도 있습니다. 다만, 이런 효울화 정도는 앱의 종류나 구성에 따라 크게 달라지지만, 어쨌든 필요한만큼만 담아 곧바로 이동할 수 있습니다. 또한, 동일한 환경 위에 여러개를 배치할 수 있습니다.
더 대단한 것은 이 가상화박스는 "공유가능한 기반"위에 놓인다는 것입니다. 즉, 같은 환경(OS)에 올라간 가상화박스들은 그 기반(커널)을 공유할 수 있습니다. 이를 통해 자원의 낭비를 대폭 줄일 수 있게 된 것입니다. 이 아이디어는 순식간에 공유되어 많은 개발자들에게 퍼져갔습니다. 이 Docker(도커)는 이삿짐박스는 우리의 상상을 초월하는 특징들이 있습니다.
완벽한 재현성: 개발자의 환경이든 실제 운영환경이든, 박스 안의 내용을 완전히 동일한 상태로 재현할 수 있습니다. 이것이 바로 멱등성(idempotence)라고 불리는 것입니다.
놀라운 경량성: 경량성은 필요한 최소한의 것만 담는 '1컨테이너 1서비스'라는 개념 덕분에 불필요한 낭비 없이 효율적인 포장이 가능합니다.
명확한 조립지침서(Dockerfile): 이케아 조립가구처럼 누구나 똑같이 쉽게 조립할 수 있는 설명서가 제공됩니다. 이를 "Dockerfile"이라고 하며, 환경구축 절차를 완벽하게 기록하고 재현할 수 있습니다.
글로벌 공유(Docker Hub): 세계최대의 "이사노하우를 가진 라이브러리"라고 할 수 있는 Docker Hub에서는 전세계 개발자들이 만든 우수한 설계도를 공유하고 있습니다.
이와 같이, Docker는 단순한 컨테이너 기술을 넘어서 개발의 상식을 바꾸는 혁신적인 도구입니다. 예를 들어, 수천개의 박스를 효율적으로 관리하는 "이사관리자"라고 할 수 있는 "쿠버네티스(Kubernetes)"라는 체계가 나왔습니다. 이 쿠버네티스는 마친 뛰어난 이사회사의 매니저와 같습니다. 수천개의 박스배치를 자동으로 관리하며 필요에 따라 늘리거나 줄일 수 있습니다. 어느 박스에 문제가 생기더라도 바로 다른 박스로 전환해줍니다. 이런 존재때문에, 개발자들은 꿈도 못꾸던 규모와 속도로 애플리케이션을 배포할 수 있게 되었습니다. 이처럼 웹개발 세계는 크게 변화했습니다. 개발자들은 더이상 환경구축에 고민하지 않고 본연의 업무인 애플리케이션 개발에 집중할 수 있게 된 것입니다.
③ Docker와 Dify
Docker가 좋다는 것은 알겠지만, 다가가기 어렵고 귀찮아하는 독자도 있을 것입니다. 특히 자신이 엔지니어가 아닌데라고 생각하는 독자가 있을 것입니다. 확실히 Docker는 처음에는 어렵다고 느낄 수 있습니다. 필자도 25년차 엔지니어지지만 처음에 Docker때문에 큰 어려움을 겪었습니다. 하지만 이를 극봅하면 멋진 세상이 나옵니다. 잘 다룰 수 있게 되면 날개를 달린 듯한 느낌을 받게 됩니다. 즉, 스마트폰이 없는 세상을 상상할 수 없듯이 Docker도 처음에는 어려워보여도, 한걸음씩 나아가면 반드시 잘 다룰수 있게 됩니다.
Dify를 Docker로 실행하는 것도 큰 장점이 있습니다. 이번에는 우선 Docker(도커)를 실행시켜 Dify(디파이)를 실행할 수 있게 만드는 것에 초점을 맞춥니다.
Docker(도커)의 단점
설정의 복잡성: Docker에서는 환경변수 및 볼륨, 네트워크등 설정항목이 많습니다. Dify(디파이)에 관한 지식뿐만 아니라. Docker고유 지식도 필요합니다.
문제해결 난관: 오류의 원인이 'Dify 문제', 'Docker 설정오류', '호스트머신의 문제'중 어느것인지 구분하기 어렵다는 것입니다. 디버깅을 위해서는 'docker exec'명령어로 컨테이너 내부로 들어가야 합니다. 성능문제는 리소스제한을 확인하는 것도 중요합니다.
(2) Docker를 사용한 설치방법
이제 각자 환경에 Docker를 실행하고 Dify를 설치해봅시다. 그전에 필요한 소프트웨어들을 준비해봅시다.
① Docker 설치 전제조건
Docker를 사용하여 Dify를 설치하는 방법을 설명합니다. 우선 Dify를 실행하기 위한 전제조건으로 아래 운영체제와 소프트웨어가 필요합니다.
② 사전준비: Git 설치
Dify 설치전에 우선 Git을 설치합니다. Git은 소스코드 관리 도구로 전세계 오픈소스가 모여있는 GitHub에서 Dify(디파이) 코드를 가져오기 위해 사용합니다.
설치가 완료되면, 아래 명령어로 Git이 제대로 설치되었는지 확인할 수 있습니다.
③ Docker 설치
Docker 설치방법은 크게 다루지 않습니다. 구글링이나 ChatGPT에서 물어봐도 충분히 설치하실 수 있습니다. 필자 개발환경은 macOS라서 macOS기준으로 화면을 캡쳐해서 설명합니다.
④ Docker 어떻게 사용하나?
Docker(도커)가 설치된 환경에서 터미널을 엽니다. macOS는 zsh 터미널, Linux는 bash터미널, Windwos라면 명령프롬프트등을 사용합니다.
터미널에서 아래 명령어를 입력해 봅시다. Docker버전을 확인할 수 있습니다.
⑤ Docker상에서 Dify 설치하기
드디어 Dify 설치를 해봅시다. 절차는 생각보다 간단합니다.
설치대상 폴더 만들기
터미널(명령프롬프트)를 엽니다. 로컬환경에서 설치하고자 하는 폴더를 만듭니다. 어디에 설치해도 상관없지만, 루트 디렉토리 바로 아래에 "app"이라는 폴더를 만듭니다.
Dify 소스코드를 가져오기
다음으로 Dify소스코드를 가져옵니다. 이는 Git을 사용하여 진행합니다. 아래 명령어를 실행합니다.
실행하면 다음과 같은 결과가 표시됩니다.
다운로드가 끝나면 "dify"폴더가 생성되고 그 안에 소스코드가 배치되었습니다.
Dify 실행하기
다음으로 생성된 dify폴더 내의 docker디렉토리로 이동후, Dify를 실행합니다.
여기부터는 약간 시간이 걸립니다. 약간 기다리다보면, 화면이 조금씩 바뀝니다. PC상태에 따라 설치 시간은 다소 차이가 있습니다. 표준사양 PC기준으로 초기 설치는 15분에서 60분정도 소요됩니다. cp명령은 기본 환경설정파일을 복사해서 .env파일을 복사해 넣는 것입니다.
Dify 설치 완료 확인
설치가 완료되고 실행까지 마무리 되면 아래와 같은 메시지가 나오면서 종료됩니다.
여기서 모든 Docker(도커) 컨테이너가 제대로 동작하는지 확인합시다.
이 명령어는 api, worker, web 3가지 비즈니스 서비스와 weaviate, db, redis, nginx 4가지 기반 컴포넌트가 포함되어 있음을 보여줍니다.
Docker Desktop에서 확인하기
설치와 실행이 완료되면 Docker Desktop을 실행합니다. 대시보드에서 "Containers"를 클릭하면 이들 컴포넌트가 동작하는 모습을 시각적으로 확인할 수 있습니다.
첫번째 Dify 실행
Dify를 사용하기 위한 준비가 완료되었습니다. 브라우저를 열고 아래 URL을 입력합니다.
로컬환경의 Dify페이지가 열립니다. 기본적으로 80번 포트로 열리는데 다른 프로그램이 80번포트를 사용중이라면 docker-compose.yml파일 내 포트설정을 변경해야 합니다.
관리자 계정 설정 및 로그인
처음 표시되는 페이지는 관리자 계정을 등록하는 화면입니다. 여기서는 기본적으로 이메일주소, 사용자명, 비밀번호를 설정합니다. 일반 브라우저에서는 계정정보가 이미 설정되어 있는 경우 기본적으로 사용자명, 비밀번호가 자동으로 채워질수도 있습니다. 입력하고 [설치]버튼을 클릭합니다.
관리자로 등록이 완료되어 다음과 같은 화면으로 전환됩니다. 이것은 로그인화면입니다. 관리화면에서 등록한 이메일주소와 비밀번호를 입력합니다. 단, 브라우저에 따라 자동입력되는 경우가 있고 [로그인]버튼을 클릭합니다.
그러면 다음과 같이 Dify 대시보드가 표시됩니다.
공했습니다. Dify(디파이) 대시보드가 나타납니다. 이제 독자의 PC에서 Dify(디파이)가 동작하고 있는 것입니다. 클라우드 환경이 아닌 독자의 환경에서 실행되는 것입니다. 이제부터 필자가 알려드리는 방법들을 꼭 실천해보시기 바랍니다.
⑥ Dify 버전 업그레이드 순서
Dify(디파이)는 매일매일 발전하고 있습ㅂ니다. 새로운 기능 추가와 개선이 자주 발생하며 최신 버전으로 업데이트하다보면 더 좋아진 환경에서 Dify(디파이)를 사용할 수 있습니다. 이번에는 안전하게 업데이트하는 방법을 쉽게 설명합니다.
데이터백업
백업은 다음 명령어로 진행합니다.
또한, 현재 설정 저장도 필요합니다. Windows사용자인 경우 volumes폴더를 백업대상 폴더로 드래그앤드롭만 하면 됩니다.
.env파일이 있는 경우 반드시 백업합니다.
사용자지정한 설정파일이 있는 경우에도 백업합니다.
동작중인 컨테이너 중지
현재 동작중인 Dify 컨테이너를 중지합니다.
최신 소스코드 가져오기
Git을 사용하여 Dify의 최신 소스코드를 가져옵니다.
최신 Docker 이미지 가져오기
Docker Hub등에서 최신 Dify이미지를 다운로드합니다.
새 버전의 Dify실행하기
백그라운드에서 새 버전의 Dify를 실행합니다.
동작확인
브라우저에서 'http://localhost'에 접속하여 Dify가 정상적으로 동작하는지 확인합니다.
주의사항
공식문서 참조: https://github.com/langgenius/dify/releases
트러블슈팅: 실행후 문제가 발생하면 아래 명령어로 로그를 확인합니다.
※ 주의사항: 오류 메시지를 확인하고, 필요에 따라 대응조치를 취하세요.
힌트
로그분석은 초보자에게는 어려울 수 있습니다. 예로 생성형AI의 도움을로 로그를 분석하는 방법니다. 아래와 같은 방법으로 로그파일을 텍스트파일로 저장합니다.
결과적으로 log00.txt파일이 만들어집니다. 이 파일을 추론성능이 좋은 생성형AI에 읽어 들여 오류를 찾아내고 원인과 대책을 제시하도록 요청합니다. 주의할 점은 V1.0.0이 공식 업데이트되면서 V0.15.3에서 동작중인 시스템을 업그레이드하려면 마이그레이션해야 합니다.
©2024-2025 GAEBAL AI, Hand-crafted & made with Damon Jaewoo Kim.
GAEBAL AI 개발사: https://gaebalai.com
AI 강의 및 개발, 컨설팅 문의: https://talk.naver.com/ct/w5umt5
AI 강의 및 개발, 컨설팅 문의: https://talk.naver.com/ct/w5umt5
