본문으로 건너뛰기

실무 가이드

환경 변수 설정​

HandStack 루트에는 환경 변수를 설정하는 스크립트가 제공됩니다.

./env.ps1

Windows 배치 환경에서는 다음 형식의 스크립트를 사용할 수 있습니다.

env.bat

Linux/macOS에서는 shell 스크립트 또는 PowerShell Core를 사용할 수 있습니다.

./env.sh
./env.ps1

팀에서 어떤 스크립트를 표준으로 쓰든 결과적으로 HANDSTACK_SRC와 HANDSTACK_HOME이 명확히 설정되어야 합니다.

설정 파일 분리​

환경별 설정 파일은 다음 기준으로 분리합니다.

  • 개발: 빠른 디버깅과 상세 로그 중심
  • 검증: 운영과 가까운 설정, 테스트 데이터 사용
  • 운영: 보안, 성능, 장애 복구 기준 적용

실행 시 별도 설정 파일을 지정할 수 있다면 --appsettings 같은 실행 인자를 사용합니다. 모듈별 설정은 module.json을 기준으로 하되, 민감정보는 별도 주입 방식으로 분리합니다.

경로 설정 기준​

상대 경로와 절대 경로를 섞어 쓰면 배포 환경에서 오류가 자주 납니다. 다음 기준을 권장합니다.

  • 소스 기준 경로는 HANDSTACK_SRC에서 시작합니다.
  • 실행 기준 경로는 HANDSTACK_HOME에서 시작합니다.
  • 모듈 기준 경로는 modules/<moduleID>에서 시작합니다.
  • 계약 파일은 contracts 또는 모듈의 Contracts 기준으로 관리합니다.

체크리스트​

  • 코드에 운영 연결 문자열이 직접 들어가 있지 않은가?
  • 문서나 샘플에 운영용 비밀값이 노출되지 않았는가?
  • 개발/검증/운영 설정 파일의 차이가 설명 가능한가?
  • HANDSTACK_SRC와 HANDSTACK_HOME을 혼동하지 않았는가?
  • 모듈 설정 변경 후 재시작 또는 재로드 기준이 문서화되어 있는가?