website: LOG_FILE_PATH 중복 접두사 버그 수정

요약

2026년 7월 21일, infra/docker-compose.yml 파일 하나를 수정했습니다. 커밋 메시지 그대로 옮기면 "LOG_FILE_PATH 중복 stage-/prod- 접두사 제거"인데, STAGE_TAG/PROD_TAG 자체가 이미 stage-<sha> / prod-<sha> 형식으로 값을 갖고 있는데 여기에 리터럴 문자열로 stage-, prod-를 또 붙이다 보니 stage-stage-<sha>.log 같은 이상한 파일명이 생기던 걸 바로잡은 작업입니다. 변경 라인은 추가 2줄, 삭제 2줄로 아주 작은 수정이지만, 로그 파일 경로가 꼬이면 나중에 로그 추적할 때 꽤 성가셔지는 부분이라 기록해둡니다.

배경 및 목적

stage/prod 환경을 분리해서 배포하면서 로그 파일도 태그별로 구분해서 남기고 싶었습니다. 그래서 docker-compose.yml에 이렇게 정의해뒀었습니다.

environment:
  - LOG_FILE_PATH=/app/logs/stage-${STAGE_TAG:-stage-latest}.log

의도는 "stage- 접두사 + STAGE_TAG 값 + .log" 형태의 파일명을 만드는 거였는데, 문제는 STAGE_TAG라는 변수 자체가 이미 stage-<sha> 형태로 주입되고 있었다는 점입니다. PROD_TAG도 마찬가지로 prod-<sha> 형식이었고요. 즉 변수 이름만 보고 "태그 값이니까 접두사가 없겠지"라고 잘못 판단해서 앞에 리터럴로 한 번 더 붙인 게 문제였습니다. 결과적으로 실제 로그 파일은 stage-stage-abc1234.log처럼 저장되고 있었고, 이런 상태로는 로그 파일명만 보고 어떤 태그인지 파악하기가 오히려 헷갈렸습니다.

구현 내용

수정된 파일은 infra/docker-compose.yml 하나이고, 추가 2줄 / 삭제 2줄로 stage 서비스와 prod 서비스 각각의 LOG_FILE_PATH 환경변수 정의부만 건드렸습니다.

stage 쪽 변경:

-      - LOG_FILE_PATH=/app/logs/stage-${STAGE_TAG:-stage-latest}.log
+      - LOG_FILE_PATH=/app/logs/${STAGE_TAG:-stage-latest}.log

prod 쪽 변경:

-      - LOG_FILE_PATH=/app/logs/prod-${PROD_TAG:-prod-latest}.log
+      - LOG_FILE_PATH=/app/logs/${PROD_TAG:-prod-latest}.log

단순히 리터럴 접두사 stage-, prod-를 삭제한 게 전부입니다. ${STAGE_TAG:-stage-latest} 부분의 기본값(:- 뒤)은 그대로 뒀는데, 이 기본값 자체도 stage-latest, prod-latest처럼 이미 접두사를 포함한 형태라 일관성이 유지됩니다. 결과적으로 STAGE_TAG가 stage-abc1234라면 로그 파일은 /app/logs/stage-abc1234.log로, 변수가 없을 때 기본값을 쓰면 /app/logs/stage-latest.log로 정상적으로 생성됩니다.

배운 점 및 개선점

이번 건은 코드 자체는 아주 단순했지만, 변수 이름과 실제 값의 포맷이 어긋나 있을 때 생기는 전형적인 실수라 기록해둘 만하다고 생각했습니다. STAGE_TAG라는 이름만 보면 "그냥 태그 값(예: 커밋 sha)이겠지"라고 짐작하기 쉬운데, 실제로는 태그 생성 스크립트 쪽에서 이미 stage- 접두사를 붙여서 넘기고 있었던 겁니다. 변수를 소비하는 쪽(docker-compose.yml)과 생성하는 쪽(태그 생성 로직)이 서로 다른 파일/다른 시점에 작성되다 보니 이런 암묵적 포맷 가정이 어긋나기 쉽다는 걸 다시 느꼈습니다.

앞으로는 환경변수를 새로 정의할 때 변수명 옆에 실제 값 예시를 주석으로 남겨두거나, .env.stage / .env.prod 파일에 태그 포맷에 대한 설명을 짧게라도 적어두는 게 좋겠다고 생각했습니다. 또한 이런 문자열 조합 버그는 로컬에서 docker compose config로 실제 렌더링된 환경변수 값을 미리 확인해보면 배포 전에 잡을 수 있었을 것 같아서, 다음부터는 compose 파일을 수정한 뒤 습관적으로 한 번 렌더링 결과를 확인해보려 합니다.