환경설정 원칙
주제 목차 · 다음: 공개 거래와 인증 점검
이 문서의 결과: 코드와 설정을 분리하는 원칙과 HandStack의 설정 계층을 설명한다.
코드와 설정을 분리하는 이유
코드는 환경이 바뀌어도 그대로 두고, 연결 문자열·포트·인증 키처럼 환경마다 달라지는 값만 설정으로 교체합니다. 설정을 코드에 고정하면 배포 환경이 바뀔 때마다 코드를 수정해야 하므로 운영 위험이 커집니다. 이 원칙은 twelvefactor 설정에서 더 자세히 다룹니다.
HandStack의 설정 계층
| 계층 | 역할 |
|---|---|
appsettings.json | ack 호스트의 포트, 모듈 목록, 경로, 보안 설정 |
module.json | 모듈의 계약 경로, 정적 자산 경로, 로그 경로, 외부 연결 설정 |
| 환경 변수 | HANDSTACK_SRC, HANDSTACK_HOME 등 |
| 실행 인자 | --port, --modules, --appsettings 같은 런타임 옵션 |
03. 프로젝트와 개발 서버에서 다룬 .localhost.json/.development.json/.test.json/.staging.json/.production.json 프리셋이 바로 이 계층을 환경별로 구분해 관리하는 방법입니다.
Windows, Ubuntu, macOS처럼 실행 OS에 따라 경로·인증서·외부 주소를 달리해야 하면 ack와 rdy는 기본 appsettings.json 뒤에 appsettings.windows.json·appsettings.linux.json·appsettings.macos.json 중 현재 OS 파일 하나를 병합합니다. 모듈도 같은 규칙으로 module.{os}.json을 사용합니다. 객체는 키별로 합치지만 배열은 OS별 파일의 전체 값으로 교체되며, 환경별 설정 파일·환경 변수·실행 인자가 그 뒤에 적용됩니다. OS별 파일은 시작할 때만 읽으므로 수정 후에는 재시작해야 합 니다. 파일 이름, 병합 규칙, 런타임 설정 감시의 제한은 ack OS별 설정 파일을 확인하세요.
실습: 지금 로드된 설정 확인하기
새 기능을 만들기 전에는 항상 다음을 먼저 확인하는 습관을 들입니다.
- 현재
HANDSTACK_HOME이 어디를 가리키는지 확인합니다. - 서버 실행 로그에서 어떤
appsettings파일이 로드됐는지 확인합니다. - 관련 모듈의
module.json에서 이번 작업과 관련된 설정값을 확인합니다.
자주 하는 오해
"로컬에서 잘 되면 운영에서도 그대로 되는 것 아닌가요?"
아닙니다. 로컬은 보통 .localhost.json 프리셋을 쓰고, 운영은 .production.json 프리셋을 씁니다. 호스트, 포트 등은 유지되지만 데이터베이스 연결이나 외부 서비스 주소처럼 URL이 아닌 값은 프리셋을 바꿔도 자동으로 바뀌지 않습니다. 각 환경 설정 파일을 직접 확인해야 합니다.
이것만 기억하세요
- 환경마다 달라지는 값은 코드가 아니라 설정으로 교체한다.
- 작업 전에는 항상 현재 로드된 설정을 먼저 확인한다.