Solana RPC Node Docker 가이드

Docker로 Solana RPC 노드를 실행하는 방법입니다.
블록 정보 조회 및 트랜잭션 브로드캐스트가 가능한 풀 RPC API(--full-rpc-api)를 제공하며, 합의에는 참여하지 않습니다(--no-voting).

참고: Setup an RPC Node

Solana 공식 문서는 라이브 클러스터(메인넷 등)의 검증자를 Docker에서 운영하는 것을 권장하지 않습니다. RPC 전용 노드는 리소스 요구가 상대적으로 낮아 Docker로 운영하는 사례가 있으며, 본 가이드는 그 구성을 제공합니다. 프로덕션·고부하 환경은 localhost 설치를 권장합니다.

빠른 시작

1. 환경 변수 (선택)

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

2. 빌드 및 실행

docker compose up -d

3. 로그 및 상태 확인

docker compose logs -f
# RPC 헬스
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' \
  http://localhost:8899

포트

데이터 디렉터리

${DATA_DIR:-./solana-data} 아래에 다음이 생성·유지됩니다.

• ledger/ — Ledger 데이터 (--limit-ledger-size로 크기 제한)
• accounts/ — Accounts DB
• identity/ — Identity 키페이어 (없으면 자동 생성)

Linux (프로덕션)

sudo mkdir -p /mnt/solana-data
sudo chown -R "$(id -u):$(id -g)" /mnt/solana-data
echo "DATA_DIR=/mnt/solana-data" >> .env

Mac/Windows

mkdir -p solana-data
# .env 기본값 ./solana-data 사용

클러스터

.env의 CLUSTER로 선택합니다.

예: 테스트넷으로 실행

CLUSTER=testnet docker compose up -d

Solana 버전

빌드 시 SOLANA_VERSION으로 GitHub 릴리스 태그 지정 (기본 v1.18.26). stable 등 채널 이름은 사용하지 않고, v1.18.26 같은 버전 태그를 사용하세요.

# .env 또는 build-arg
SOLANA_VERSION=v1.18.26
docker compose build --build-arg SOLANA_VERSION=v1.18.26
docker compose up -d

RPC 사용 예시

getSlot (최신 슬롯)

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}' \
  http://localhost:8899

getBlock (블록 조회)

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlock","params":[0]}' \
  http://localhost:8899

sendTransaction (트랜잭션 브로드캐스트)

서명된 트랜잭션을 base64로 전송합니다. 클라이언트 라이브러리(@solana/web3.js 등) 사용 시 해당 노드 RPC URL을 http://localhost:8899로 지정하면 됩니다.

노드 관리

하드웨어 권장

• CPU: AVX2 지원 x86_64, 16코어 이상 권장
• RAM: 256 GB 이상 권장 (account-index 사용 시 512 GB+)
• 디스크: NVMe SSD, Ledger·Accounts 합쳐 1.5 TB 이상 권장
• 네트워크: 1 Gbit/s 대칭 이상

Apple Silicon (M1/M2)

Solana 공식 바이너리는 x86_64 전용입니다. Dockerfile과 docker-compose에서 platform: linux/amd64를 사용하므로, M1/M2에서는 amd64 이미지가 에뮬레이션으로 실행됩니다. 빌드·실행 모두 동작하지만, 성능은 네이티브보다 낮을 수 있습니다. 프로덕션·고부하는 x86_64 호스트 또는 localhost 설치(소스 빌드)를 권장합니다.

문제 해결

• 동기화 느림: 디스크 I/O·네트워크 확인. Ledger와 Accounts를 별도 디스크에 두는 구성을 권장.
• RPC 연결 실패: docker compose ps, docker compose logs로 기동 여부 확인. 호스트 방화벽에서 8899, 8900, 8000-8020 개방 여부 확인.
• 디스크 부족: --limit-ledger-size가 적용된 RPC 노드이므로, 장기적으로는 Ledger 디스크 용량을 모니터링하세요.

자세한 트러블슈팅은 localhost troubleshooting 및 Solana Validator 문서를 참고하세요.

참고 링크

• Setup an RPC Node
• Available Clusters
• Solana RPC API