이 가이드는 Ubuntu 환경 기준으로 작성되었습니다. Solana는 로컬 개발용 테스트 노드를 쉽게 구축할 수 있도록 도커 이미지와 전용 명령어를 제공합니다. 아래 단계를 따라 로컬 검증 노드를 구성하고 개발 환경을 점검할 수 있습니다.

기본 환경 준비

도커가 시스템에 정상 설치되어 있어야 하며, 추가적으로 Node.js 및 npm을 활용해 개발 도구를 관리할 수 있습니다.

sudo apt update
sudo apt install nodejs npm -y

설치 후 버전 확인:

node -v  # 예: v18.x 이상 권장
npm -v   # 예: 9.x 이상 권장

프로젝트 초기화 및 웹3.js 설치

로컬 작업 디렉터리를 생성하고, @solana/web3.js 라이브러리를 설치합니다.

mkdir solana-local-env && cd solana-local-env
npm init -y
npm install @solana/web3.js

주의: npm install 중 오류 발생 시, 먼저 npm을 최신 버전으로 업그레이드하세요.
명령어: npm install -g npm@latest

스크립트 설정 (package.json)

package.json 파일 내 scripts 섹션에 다음 항목을 추가하여 로컬 노드 제어를 간편하게 할 수 있습니다.

"scripts": {
  "validator:start": "solana-test-validator --log > validator.log 2>&1 &",
  "validator:stop": "pkill solana-test-validator || true",
  "logs:follow": "tail -f validator.log",
  "logs:filter": "tail -f validator.log | grep -i 'your_program_key'"
}

Solana CLI 설치

공식 설치 스크립트를 통해 최신 버전의 Solana 도구군을 다운로드합니다.

sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

설치 후 터미널 세션을 재시작하거나, PATH를 수동으로 로드하여 solana 명령어 사용 가능 상태로 만듭니다.

로컬 검증 노드 실행

다음 명령어로 백그라운드에서 테스트 네트워크를 구동합니다.

nohup solana-test-validator --log > solana.log 2>&1 &

• --log: stdout으로 로그 출력 활성화
• > solana.log: 표준 출력을 파일로 리디렉션
• 2>&1: 에러 스트림 포함
• &: 백그라운드 실행

로그 실시간 모니터링:

tail -f solana.log

RPC 연결 테스트

노드가 정상 작동 중인지 확인하기 위해 RPC 요청을 전송합니다.

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

정상 응답 예시:

{"jsonrpc":"2.0","result":"abcd1234","id":1}

응답값이 반환되면 로컬 네트워크가 성공적으로 구동된 것입니다.

CLI 기본 설정 변경

Solana CLI가 자동으로 로컬 노드를 타겟하도록 URL을 지정합니다.

solana config set --url http://localhost:8899

설정 적용 확인:

solana config get

클러스터 버전 확인

현재 실행 중인 Solana 버전을 조회합니다.

solana cluster-version

출력 예: 1.17.17 (stable 릴리스 기준)

고급 실행 옵션

필요 시 커스텀 설정으로 노드를 시작할 수 있습니다.

solana-test-validator \
  --rpc-port 8899 \
  --websocket-port 8900 \
  --ledger ./custom-ledger \
  --quiet

• --rpc-port: HTTP RPC 포트 지정
• --websocket-port: WebSocket 엔드포인트 포트
• --ledger: 장부 데이터 저장 위치
• --quiet: 불필요한 로그 억제

소스 코드 기반 빌드 (선택 사항)

최신 기능 테스트를 위해 GitHub 저장소에서 직접 빌드할 수 있습니다.

git clone https://github.com/solana-labs/solana.git
cd solana
./install/cargo-install-all.sh
export PATH="$PWD/bin:$PATH"

빌드 후 동일한 solana-test-validator 명령어로 노드 구동이 가능합니다.