Docker Compose 배포

이 페이지에서는 Docker Compose로 Hagicode를 배포하는 방법을 설명합니다. 서버, NAS, 팀 공유, 또는 환경 격리가 필요한 시나리오에 적합합니다. 개인 로컬 사용에는 Microsoft Store 또는 Desktop을 먼저 고려하세요.

Docker Compose를 선택하는 이유

• 환경이 격리되어 종속성 충돌이 적습니다
• 현재 지원하는 Hagicode 서비스 스택을 한 번에 시작할 수 있습니다
• 구성, 업그레이드, 유지 관리 경로가 일관됩니다
• 호스트에는 Docker만 있으면 되며, Node.js나 Git을 따로 설치할 필요가 없습니다

기본 데이터 저장에 대하여

현재 지원하는 Docker Compose 템플릿은 기본 로컬 SQLite 데이터 경로를 기준으로 영구 데이터를 구성합니다. 대부분의 경우 호스트에 별도의 데이터베이스 서비스를 준비할 필요가 없습니다.

비디오 튜토리얼

전체 흐름을 먼저 보고 싶다면 비디오 튜토리얼부터 시청하세요.

Bilibili에서 비디오 튜토리얼 보기

비디오 내용 소개:

• Docker Compose 배포의 전체 과정 시연
• 구성 파일 생성 및 수정 안내
• 서비스 시작 및 확인 단계
• 자주 발생하는 문제와 해결 방법

영상 길이: 약 15분

사전 요구 사항

시작하기 전에 시스템에 Docker와 Docker Compose가 설치되어 있는지 확인하세요.

Docker 설치

Windows

Docker Desktop for Windows를 내려받아 설치합니다. 설치가 끝나면 Docker Desktop이 실행 중인지 확인하세요.

macOS

Docker Desktop for Mac을 내려받아 설치합니다. 설치가 끝나면 Docker Desktop이 실행 중인지 확인하세요.

Linux

Docker 공식 문서에 따라 사용 중인 배포판에 Docker Engine과 Docker Compose 플러그인을 설치합니다: Install Docker Engine. 배포판마다 소프트웨어 저장소와 패키지 이름이 다르므로 다른 배포판의 명령을 그대로 사용하지 마세요.

설치가 끝나면 Docker 서비스를 시작하고 부팅 시 자동으로 시작되도록 설정합니다.

sudo systemctl start docker
sudo systemctl enable docker

설치 확인

설치가 끝나면 다음 명령을 실행해 Docker와 Docker Compose가 올바르게 설치되었는지 확인합니다.

docker --version
docker compose version

빠른 시작

1. Docker Compose 구성 파일 생성

Docker Compose Builder로 docker-compose.yml을 생성합니다. 이 도구는 독립 사이트이며, 생성 규칙과 업데이트는 해당 사이트를 기준으로 합니다.

생성기는 다음을 지원합니다.

• API 제공자 선택(Zhipu AI, Anthropic 공식, 사용자 지정 API) 및 API URL과 Token 설정
• 포트, 컨테이너 이름, 영구 데이터 디렉터리, 작업 디렉터리 사용자 지정
• 내장 데이터베이스 또는 외부 데이터베이스 선택
• Windows / Linux 플랫폼 차이와 일반적인 파일 권한 문제 자동 처리
• 지원되는 Docker Hub 이미지 사용

진행 순서는 다음과 같습니다.

1. Docker Compose Builder를 엽니다.
2. 필요에 맞게 구성을 입력합니다. API 제공자를 선택하고 포트, 데이터베이스, 작업 디렉터리 등의 옵션을 설정합니다.
3. 생성 버튼을 클릭해 docker-compose.yml 구성을 가져옵니다.
4. 생성된 구성을 docker-compose.yml 파일로 저장합니다.
5. 필요하면 .env 파일을 만들어 민감한 정보를 설정하고, Token을 compose 파일에 직접 쓰지 않도록 합니다.

이미지 소스

생성기는 Docker Hub를 지원되는 이미지 소스로 사용합니다.

• 이미지 주소: newbe36524/hagicode:{tag}
• 적용 시나리오: Docker Hub 이미지 가속을 지원하는 사용자에게 적합합니다
• 참고 사항: 일부 지역에서는 이미지 가속기(미러) 설정이 필요할 수 있습니다

API Token 받기

Docker 배포는 생성기에서 설정한 API 제공자를 통해 모델에 접근하므로, 먼저 사용 가능한 API Token을 준비해야 합니다.

Zhipu AI: API Token 받기 →

• 중국 내에서 안정적으로 접속할 수 있고 응답이 더 빠릅니다
• 가성비가 높아 일상적인 사용에 적합합니다

Anthropic 공식: API Token 받기 →

• Anthropic 서비스를 직접 사용합니다

생성기에서 사용자 지정 API를 선택할 수도 있습니다.

2. 서비스 시작

docker-compose.yml이 있는 디렉터리에서 다음 명령을 실행합니다.

docker compose up -d

이 명령은 다음을 수행합니다.

• 생성된 구성에 정의된 Hagicode 컨테이너를 내려받고 시작합니다
• 네트워크를 생성하고 구성합니다
• 기본 데이터 디렉터리와 런타임 종속성을 초기화합니다

3. 서비스 상태 확인

컨테이너가 실행 중인지 확인합니다.

docker compose ps

생성된 구성에 정의된 서비스가 “running” 상태로 표시되어야 합니다.

서비스 로그를 확인합니다.

# 모든 서비스 로그 보기
docker compose logs

# Hagicode 서비스 로그 보기
docker compose logs hagicode

# 로그를 실시간으로 따라가기
docker compose logs -f hagicode

애플리케이션 접속

서비스가 정상적으로 시작되면 브라우저에서 다음 주소로 접속합니다.

http://localhost:45000

생성기에서 포트를 변경했다면 설정한 호스트 포트를 사용하세요. 처음 열면 초기화 마법사가 나타나므로 초기화 마법사 설정을 이어서 읽어 보세요.

구성 안내

포트 변경, API 제공자 전환 등 구성을 수정해야 하는 경우 다음과 같이 할 수 있습니다.

1. Docker Compose Builder로 새 구성을 다시 생성합니다
2. docker-compose.yml과 .env 파일을 직접 수정합니다
3. 컨테이너를 다시 생성해 구성을 적용합니다.

docker compose up -d

docker compose restart는 기존 컨테이너를 다시 시작할 뿐, docker-compose.yml이나 .env의 변경 사항을 적용하지 않습니다. 구성을 수정한 뒤에는 docker compose up -d를 사용하세요.

데이터 지속성

현재 지원하는 Docker Compose 경로는 기본적으로 SQLite 데이터 파일과 영구 볼륨을 사용합니다. 데이터 마운트 위치나 백업 전략을 확인해야 한다면, 생성된 docker-compose.yml의 볼륨 및 데이터 디렉터리 매핑 구성을 직접 살펴보세요.

일상 유지 관리

중지 및 시작

# 서비스 중지(컨테이너와 데이터 유지)
docker compose stop

# 다시 시작
docker compose start

# 중지하고 컨테이너 제거(데이터 볼륨은 그대로 유지)
docker compose down

docker compose down에 -v를 함부로 붙이지 마세요. compose 파일에 선언된 데이터 볼륨까지 함께 삭제됩니다.

버전 업그레이드

1. 업그레이드하기 전에 데이터 디렉터리를 먼저 백업합니다(아래 참고).
2. docker-compose.yml의 이미지 태그 newbe36524/hagicode:{tag}를 대상 버전으로 바꾸거나, 생성기로 구성을 다시 생성합니다.
3. 새 이미지를 받아 컨테이너를 다시 생성합니다.

docker compose pull
docker compose up -d

데이터 백업

먼저 docker compose stop을 실행해 서비스가 더 이상 데이터를 쓰지 않게 한 다음, docker-compose.yml의 볼륨 및 데이터 디렉터리 매핑에 해당하는 디렉터리나 데이터 볼륨을 백업하고, 이어서 docker compose start로 서비스를 다시 시작합니다.

다음 단계

이제 Hagicode 배포를 마쳤습니다. 다음 순서로 진행하세요.

1. 초기화 마법사 설정을 읽고 기본 Hagicoder와 첫 프로젝트를 만듭니다.
2. 대화 세션 만들기에서 먼저 읽기 전용 모드로 프로젝트를 파악한 뒤, 필요에 따라 제안 세션 만들기로 이어 갑니다.

데스크톱 애플리케이션을 선호한다면 Desktop 설치 가이드를 참고하세요.