Docker로 빠르게 시작해보는 Freqtrade

다음은 Freqtrade 공식문서중 Using Freqtrade with Docker 를 번역한 것입니다

Docker를 이용한 Freqtrade 퀵스타트

이 문서는 Docker를 사용하여 봇을 실행하는 방법을 설명합니다. 바로 실행되는 것은 아니며, 문서 전체를 읽고 올바르게 설정하는 방법을 이해해야 합니다.

Docker 설치 (Install Docker)

먼저 사용 중인 플랫폼에 맞는 Docker / Docker Desktop을 다운로드하여 설치하세요.

• Mac
• Windows
• Linux

참고: Freqtrade 문서는 Docker Desktop(또는 docker compose 플러그인) 사용을 가정합니다. docker-compose 단독 설치도 작동하지만, 모든 명령어의 docker compose를 docker-compose로 변경해야 합니다 (예: docker compose up -d -> docker-compose up -d).

Windows 사용자 주의:
Windows에 Docker를 막 설치했다면 반드시 재부팅하세요. 그렇지 않으면 컨테이너 연결과 관련된 설명할 수 없는 네트워크 문제가 발생할 수 있습니다.

---

Docker로 Freqtrade 사용하기 (Freqtrade with docker)

Freqtrade는 Dockerhub에 공식 이미지를 제공하며, 바로 사용할 수 있는 docker compose 파일도 제공합니다.

참고: 아래 섹션은 Docker가 설치되어 있고 로그인한 사용자가 사용할 수 있다고 가정합니다.
모든 명령어는 docker-compose.yml 파일이 있는 디렉터리에서 실행해야 합니다.

Docker 퀵스타트 (Docker quick start)

새 디렉터리를 만들고 그 안에 docker-compose 파일을 저장합니다.

mkdir ft_userdata
cd ft_userdata/

# 저장소에서 docker-compose 파일 다운로드
curl https://raw.githubusercontent.com/freqtrade/freqtrade/stable/docker-compose.yml -o docker-compose.yml

# freqtrade 이미지 다운로드 (Pull)
docker compose pull

# 사용자 디렉터리 구조 생성
docker compose run --rm freqtrade create-userdir --userdir user_data

# 설정 생성 - 대화형 질문에 답변해야 함
docker compose run --rm freqtrade new-config --config user_data/config.json

위 명령어들은 ft_userdata라는 새 디렉터리를 만들고, 최신 compose 파일을 다운로드하며, 이미지를 가져옵니다. 마지막 두 단계는 user_data 디렉터리를 생성하고, 사용자의 선택에 따라 기본 설정(config.json)을 만듭니다.

봇 설정 수정 방법 (How to edit the bot configuration?)

설정은 user_data/config.json 파일(ft_userdata 디렉터리 내)을 수정하여 언제든 변경할 수 있습니다.
또한 docker-compose.yml 파일의 command 섹션을 수정하여 전략이나 명령어를 변경할 수 있습니다.

커스텀 전략 추가하기 (Adding a custom strategy)

1. 설정 파일은 user_data/config.json에 있습니다.
2. 커스텀 전략 파일을 user_data/strategies/ 디렉터리에 복사합니다.
3. docker-compose.yml 파일에 전략 클래스 이름을 추가합니다.

기본적으로 SampleStrategy가 실행됩니다.

주의: SampleStrategy는 단순 예시용입니다! 실제 돈을 투자하기 전에 반드시 나만의 전략을 백테스팅하고 일정 기간 모의 투자(Dry-run)를 하세요.

준비가 되었다면 트레이딩 모드(Dry-run 또는 Live)로 봇을 실행합니다.

docker compose up -d

기본 설정 확인: 생성된 설정이 대부분 작동하지만, 봇을 시작하기 전에 가격 설정(Pricing), 페어 리스트(pairlist) 등 옵션이 원하는 대로 되어 있는지 확인해야 합니다.

---

UI 접속하기 (Accessing the UI)

new-config 단계에서 FreqUI 사용을 선택했다면 localhost:8080 포트에서 FreqUI를 사용할 수 있습니다.
브라우저 주소창에 http://localhost:8080을 입력하여 접속하세요.

원격 서버(VPS)에서 UI 접속 시:
VPS를 사용 중이라면 보안을 위해 SSH 터널링이나 VPN(openVPN, wireguard)을 사용하는 것을 권장합니다. FreqUI를 인터넷에 직접 노출하는 것은 보안상 권장되지 않습니다(기본적으로 HTTPS를 지원하지 않음).

---

봇 모니터링 (Monitoring the bot)

실행 중인 인스턴스는 다음 명령어로 확인합니다.

docker compose ps

freqtrade 서비스가 running 상태여야 합니다. 그렇지 않다면 로그를 확인하세요.

로그 확인 (Docker compose logs)

로그 파일 위치: user_data/logs/freqtrade.log
최신 로그 실시간 확인 명령어:

docker compose logs -f

데이터베이스 (Database)

데이터베이스 위치: user_data/tradesv3.sqlite

---

Docker로 업데이트하기 (Updating freqtrade with docker)

Docker 사용 시 업데이트는 다음 두 명령어면 충분합니다.

# 최신 이미지 다운로드
docker compose pull

# 이미지 재시작
docker compose up -d

이 명령어는 최신 이미지를 가져온 후, 방금 가져온 버전으로 컨테이너를 재시작합니다.

변경 사항 확인: 항상 변경 로그(Changelog)를 확인하여 수동 개입이 필요한 부분이나 호환성 문제가 없는지 확인하세요.

---

docker-compose 파일 수정 (Editing the docker-compose file)

고급 사용자는 docker-compose 파일을 수정하여 모든 옵션과 인자를 포함할 수 있습니다.
모든 freqtrade 인자는 다음과 같이 실행하여 사용할 수 있습니다.

docker compose run --rm freqtrade <명령어> <선택적 인자>

참고: 트레이딩 명령어(freqtrade trade ...)는 docker compose run으로 실행하지 말고 docker compose up -d를 사용하세요. 그래야 컨테이너가 포트 포워딩을 포함해 올바르게 시작되고 시스템 재부팅 후에도 자동 재시작됩니다.

데이터 다운로드 예시 (Example: Download data with docker)

Binance에서 ETH/BTC 페어의 1시간 봉 데이터를 5일치 다운로드하여 user_data/data/에 저장합니다.

docker compose run --rm freqtrade download-data --pairs ETH/BTC --exchange binance --days 5 -t 1h

백테스팅 예시 (Example: Backtest with docker)

SampleStrategy 전략으로 5분 봉 데이터를 사용하여 특정 기간(20190801-20191001) 백테스팅을 실행합니다.

docker compose run --rm freqtrade backtesting --config user_data/config.json --strategy SampleStrategy --timerange 20190801-20191001 -i 5m

---

추가 의존성 설치 (Additional dependencies with docker)

전략에 기본 이미지에 없는 라이브러리가 필요하다면 이미지를 직접 빌드해야 합니다.

1. 필요한 의존성 설치 단계가 포함된 Dockerfile을 만듭니다 (예: docker/Dockerfile.custom 참조).
2. docker-compose.yml 파일에서 build 단계 주석을 해제하고 이미지 이름을 변경합니다.

image: freqtrade_custom
build:
  context: .
  dockerfile: "./Dockerfile.<확장자>"

3. docker compose build --pull 명령어로 이미지를 빌드한 후 위에서 설명한 대로 실행합니다.

---

플롯팅 (Plotting with docker)

수익이나 데이터프레임을 시각화하려면 docker-compose.yml 파일에서 이미지를 *_plot으로 변경해야 합니다. 그 후 다음 명령어를 사용할 수 있습니다.

docker compose run --rm freqtrade plot-dataframe --strategy AwesomeStrategy -p BTC/ETH --timerange=20180801-20180805

결과는 user_data/plot 디렉터리에 저장되며 브라우저로 열 수 있습니다.

---

데이터 분석 (Data analysis using docker compose)

Jupyter Lab 서버를 실행하여 데이터 분석을 할 수 있습니다.

docker compose -f docker/docker-compose-jupyter.yml up

실행 후 콘솔에 출력되는 링크(예: https://127.0.0.1:8888/lab...)를 통해 접속합니다.

---

문제 해결 (Troubleshooting)

Windows에서 Docker 사용 시

에러: *"Timestamp for this request is outside of the recvWindow."*
Docker 컨테이너의 시간이 과거로 틀어지면서 API 요청 동기화에 실패하는 문제입니다.

• 임시 해결: wsl --shutdown 실행 후 Docker 재시작.
• 영구 해결: Linux 호스트 사용 권장 또는 작업 스케줄러로 WSL 주기적 재시작.

경고: 위와 같은 문제 때문에 프로덕션(실전) 환경에서는 Windows Docker 사용을 권장하지 않습니다. 실전 매매는 Linux VPS를 사용하세요.