개요

설정 원칙은 코드와 설정을 분리하는 것입니다. 같은 코드가 개발, 검증, 운영 환경에서 실행되더라도 연결 문자열, 포트, 파일 경로, 인증 키, 외부 서비스 주소는 환경에 따라 달라질 수 있습니다.

HandStack은 appsettings.json, 환경 변수, 모듈별 module.json, 실행 인자, 관리 스크립트를 조합하여 실행 설정을 만듭니다. 설정을 코드에 고정하면 배포 환경이 바뀔 때마다 코드를 수정해야 하므로 운영 위험이 커집니다.

HandStack 설정의 계층

HandStack에서 자주 다루는 설정은 다음과 같습니다.

• HANDSTACK_SRC: HandStack 소스 위치
• HANDSTACK_HOME: 실행 또는 배포 기준 위치
• appsettings.json: ack 호스트의 포트, 모듈 목록, 경로, 보안 설정
• module.json: 모듈의 계약 경로, 정적 자산 경로, 로그 경로, 외부 연결 설정
• 실행 인자: --port, --modules, --appsettings 같은 런타임 옵션
• 운영 스크립트 매개변수: development, staging, production 같은 환경 구분

설정의 핵심은 "환경마다 달라지는 값은 코드가 아니라 설정으로 교체한다"는 점입니다.

민감정보 기준

인증 키, 암호, API 토큰, 연결 문자열은 공개 문서와 저장소에 직접 적지 않습니다. 개발 예시는 더미 값을 사용하고, 실제 값은 서버 환경 변수, 보안 저장소, 배포 자동화의 자격 증명 기능으로 주입합니다.

문서에서는 다음처럼 표현합니다.

ManagementKey=<배포 관리 키>
ConnectionString=<데이터베이스 연결 문자열>
ApiToken=<외부 서비스 토큰>

마치며

HandStack 설정 관리는 실행 환경을 재현 가능하게 만드는 작업입니다. 신규 개발자는 기능 구현 전에 현재 실행 중인 HANDSTACK_HOME, 로드된 appsettings, 모듈별 module.json을 확인하는 습관을 가져야 합니다.