portfolio-hub/docs/technical/settings-and-env-loading.md

Settings and Env Loading

• Related REQ: N/A

목표

설정값 로딩 경로를 단일화하여 로컬/운영 간 동작 차이를 최소화하고, 보안 민감 값을 안전하게 주입한다.

설정 로딩 우선순위

1. 환경 변수
2. .env 파일
3. 코드 기본값

핵심 설정 그룹

그룹	예시 키	목적
API/CORS	PORTFOLIOHUB_ALLOWED_ORIGINS	브라우저 호출 허용 오리진 제어
인증/권한	PORTFOLIOHUB_READ_TOKENS, PORTFOLIOHUB_TRADE_WRITE_TOKENS, PORTFOLIOHUB_ADMIN_TOKENS	정적 토큰 기반 접근 제어
세션/토큰 TTL	PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS 등	DB 발급 토큰 만료 정책
Bootstrap User	PORTFOLIOHUB_BOOTSTRAP_USERNAME, PORTFOLIOHUB_BOOTSTRAP_PASSWORD	초기 admin 사용자 생성
DB 연결	TIMESCALEDB_*	Postgres/Timescale 접속 정보
Observability	LOKI_*, REDIS_*	중앙 로그/캐시 운영 확장 포인트

상세 설정 명세

핵심 설정:

• PORTFOLIOHUB_ALLOWED_ORIGINS: comma-separated CORS origins
• PORTFOLIOHUB_BOOTSTRAP_USERNAME: users 테이블이 비어 있을 때 생성할 초기 username
• PORTFOLIOHUB_BOOTSTRAP_EMAIL: bootstrap user의 선택적 email
• PORTFOLIOHUB_BOOTSTRAP_PASSWORD: 초기 admin password
• PORTFOLIOHUB_READ_TOKENS: comma-separated read tokens
• PORTFOLIOHUB_TRADE_WRITE_TOKENS: comma-separated trade-write tokens
• PORTFOLIOHUB_ADMIN_TOKENS: comma-separated admin tokens
• PORTFOLIOHUB_DB_ENABLED: true일 때 DB repository 활성화
• PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS: login session token TTL(hours)
• PORTFOLIOHUB_CLIENT_TOKEN_DEFAULT_TTL_DAYS: client token 기본 TTL(days)
• PORTFOLIOHUB_BOT_TOKEN_DEFAULT_TTL_DAYS: bot token 기본 TTL(days)

DB 활성 설정:

• TIMESCALEDB_HOST
• TIMESCALEDB_PORT
• TIMESCALEDB_NAME
• TIMESCALEDB_USER
• TIMESCALEDB_PASSWORD
• TIMESCALEDB_SSLMODE
• TIMESCALEDB_CONNECT_TIMEOUT_SEC
• TIMESCALEDB_APPLICATION_NAME

파생 설정:

• active_database_url은 psycopg PostgreSQL URL 포맷으로 credentials와 query options를 인코딩해 구성한다.

CORS 정책

CORS middleware는 다음 기준으로 동작한다.

• allow_origins: 구성된 origins 목록 사용
• allow_credentials = true
• allow_methods = ["GET", "POST", "PATCH", "DELETE", "OPTIONS"]
• allow_headers = ["Authorization", "Content-Type"]

브라우저 기반 frontend가 HTTPS로 접근하면 PORTFOLIOHUB_ALLOWED_ORIGINS에는 정확한 HTTPS origin만 명시한다.

예시:

PORTFOLIOHUB_ALLOWED_ORIGINS=https://app.example.com,https://www.example.com

운영 규칙

• 운영 환경에서는 .env 대신 배포 플랫폼의 환경 변수 주입을 우선한다.
• PORTFOLIOHUB_DB_ENABLED=true일 때 TIMESCALEDB_* 필수 키 누락 여부를 시작 시 검증한다.
• 민감 값은 문서/샘플에 실제 비밀 값을 기록하지 않는다.

Validation Notes

• 필수 키 누락 시 명확한 예외 메시지로 기동 실패해야 한다.
• CORS 오리진 파싱은 공백/쉼표 변형 입력에도 안정적으로 동작해야 한다.
• 부트스트랩 계정 자동 생성은 users 테이블이 비어 있을 때만 수행되어야 한다.

Open Implementation Points

• 설정 스키마를 strict mode로 고정할지(미정의 키 거부) 여부를 확정한다.
• Redis/Loki 활성화 플래그와 실패 시 동작(무시/실패)을 명시적으로 분리할지 결정한다.