XRP Ledger 노드 Docker 가이드

Docker를 사용하여 XRP Ledger (rippled) 노드를 실행하는 방법입니다.
공식 문서 및 커뮤니티 이미지와 함께 사용하는 것을 권장합니다.

이 가이드는 개념과 기본 실행 예시를 제공하며, 반드시 최신 XRPL 공식 문서를 함께 참고하세요.

• 공식 문서: Run a Private Network with Docker
• Docker Hub: xrpllabsofficial/xrpld

빠른 시작

1. Docker 설치

Ubuntu 예시:

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker

2. XRP Ledger Docker 이미지 받기

docker pull xrpllabsofficial/xrpld:latest

버전 태그는 Docker Hub 및 공식 릴리스를 참고해 운영 환경에 맞게 고정하는 것이 좋습니다.

3. 설정 디렉토리 준비

sudo mkdir -p /mnt/cryptocur-data/xrp/config

# 권한은 운영 환경에 맞게 조정
sudo chown -R $USER:$USER /mnt/cryptocur-data/xrp
sudo chmod -R 755 /mnt/cryptocur-data/xrp

/mnt/cryptocur-data/xrp/config 아래에 필요하다면 rippled.cfg, validators.txt 등을 둘 수 있습니다.
없으면 컨테이너의 기본 설정으로 시작합니다.

4. 단일 docker run 예시

docker run -dit \
  --name rippled \
  -p 80:80 \           # HTTP/WebSocket (공개용, 필요 시만 노출)
  -p 5005:5005 \       # 로컬 admin RPC
  -v /mnt/cryptocur-data/xrp/config/:/config/ \
  xrpllabsofficial/xrpld:latest

기본 설정에서는 약 256개의 레저 히스토리를 유지하며, 설정 파일로 조정할 수 있습니다.

docker-compose 예시

여러 옵션을 한 곳에서 관리하려면 docker-compose.yml을 사용할 수 있습니다.

version: '3.8'

services:
  rippled:
    image: xrpllabsofficial/xrpld:latest
    container_name: rippled
    restart: unless-stopped
    ports:
      - "80:80"      # HTTP/WebSocket
      - "5005:5005"  # Admin RPC (로컬 전용 권장)
    volumes:
      - /mnt/cryptocur-data/xrp/config:/config

실행:

docker-compose up -d
docker-compose logs -f

노드 상태 확인

docker logs -f rippled

# server_info 확인
docker exec rippled server_info

complete_ledgers 값이 증가하면 노드가 정상적으로 동기화 중입니다.

Standalone / 프라이빗 네트워크

테스트용 프라이빗 네트워크 또는 standalone 모드는 XRPL 공식 문서의 Docker 예시를 참고하세요.

• Run a Private Network with Docker

Localhost 설치

호스트에 직접 rippled를 설치하는 방법은 ../localhost/README.md를 참고하세요.

XRP Ledger (rippled) Docker 가이드

Docker로 XRP Ledger 메인넷 노드(rippled)를 실행하는 방법입니다. 공식 이미지(xrpllabsofficial/xrpld)를 사용합니다.

빠른 시작

1. 환경 변수 (선택)

cp .env.example .env
# 필요 시 DATA_DIR, WS_PORT 수정

2. 실행

docker compose up -d

3. 상태 확인

docker compose logs -f
docker exec ripple-node rippled server_info

server_state가 full 또는 proposing이면 동기화 완료입니다. 최초 동기화에는 수 분~수십 분이 걸릴 수 있습니다.

포트

.env에서 WS_PORT=8080처럼 바꾸면 호스트 8080 → 컨테이너 80으로 매핑할 수 있습니다.

데이터 저장

블록체인 DB는 ${DATA_DIR:-./ripple-data}에 저장됩니다.

Linux (프로덕션)

sudo mkdir -p /mnt/cryptocur-data/ripple
sudo chown -R 1000:1000 /mnt/cryptocur-data/ripple
echo "DATA_DIR=/mnt/cryptocur-data/ripple" >> .env

Mac/Windows

mkdir -p ripple-data
# .env 기본값 ./ripple-data 그대로 사용

노드 관리

RPC 테스트

HTTP/JSON-RPC로 노드 동작을 확인하는 방법은 **RPC-TESTS.md**를 참고하세요.
(server_info, ledger, account_info, fee, tx, 배치 요청, Docker CLI, WebSocket 예제 포함)

API 사용

WebSocket (기본 포트 80)

# 로컬
curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"method":"server_info","params":[{}]}' \
  http://localhost:80

클라이언트 라이브러리: xrpl.js, HTTP/WebSocket APIs.

Admin RPC (로컬 전용, 5005)

docker exec ripple-node rippled server_info

선택: 사용자 설정 마운트

기본 설정 대신 rippled.cfg를 쓰려면:

1. config/rippled.cfg, 필요 시 config/validators.txt 준비 (예: WietseWind/docker-rippled config).
2. docker-compose.yml의 volumes에 다음 추가:

   - ./config:/config/
   

설정에서 [database_path]를 바꾼 경우, 해당 경로를 volume으로 마운트해야 합니다.

Apple M1/M2

이미지가 amd64이므로 다음처럼 플랫폼을 지정하세요.

# docker-compose.yml 서비스에 추가
services:
  rippled:
    platform: linux/amd64

또는:

docker compose run --rm -e DOCKER_DEFAULT_PLATFORM=linux/amd64 ...

한 번에 쓰려면 docker-compose.yml에 platform: linux/amd64를 넣어두면 됩니다.

이미지 버전

• latest: 최신 안정 버전 (권장).
• 프로덕션에서는 태그로 고정할 수 있습니다: xrpllabsofficial/xrpld:2.6.2

업데이트:

docker compose pull
docker compose up -d

문제 해결

• 동기화 안 됨: rippled Server Doesn't Sync
• 시작 실패: rippled Server Won't Start
• 로그: docker compose logs -f 또는 Understanding Log Messages

참고

• XRPL Installation
• WietseWind/docker-rippled — 설정 예제 및 설명
• Run a Private Network with Docker — 사설망용 (메인넷 아님)