Docker Compose 환경 분리 완벽 가이드: 개발/운영 .env 오버라이딩 아키텍처

11월 09, 2026

[Productivity] Docker Compose 환경 분리 완벽 가이드: .env 오버라이딩 아키텍처

"팀원들과 로컬에서 개발할 때는 docker-compose up으로 데이터베이스와 서버를 편하게 띄웠습니다. 그런데 이 코드를 그대로 운영(Production) 서버에 들고 가니, 테스트용으로 뚫어놓은 포트가 외부에 다 노출되고 소스코드에 하드코딩된 DB 비밀번호가 깃허브에 그대로 올라가는 재앙이 벌어졌습니다."

도커(Docker)를 로컬 개발용 장난감에서 실제 엔터프라이즈 인프라로 격상시킬 때 반드시 극복해야 하는 '환경 격리'의 병목입니다. 똑같은 컨테이너를 띄우지만, 로컬 PC와 운영 서버는 완전히 다른 보안 및 포트 바인딩 규칙을 가져야 합니다.

초보자들은 docker-compose-dev.yml, docker-compose-prod.yml 처럼 파일을 여러 개 만들고 배포할 때마다 옵션을 길게 적어 넣는 노동을 반복합니다. 본 가이드에서는 도커 엔진이 텍스트 파일을 덮어쓰는(Merge) 메커니즘을 해체하고, 단 한 줄의 명령어로 환경을 지능적으로 분리하는 오버라이딩(Overriding) 아키텍처를 단호하게 제시합니다.

📌 이 글의 핵심 포인트

보안의 핵심 (.env): 비밀번호와 API 키를 yml 파일에서 완전히 도려내어 깃허브(GitHub) 유출을 방어하는 환경 변수 분리

기본 뼈대 구성: 모든 환경에서 공통으로 쓰이는 베이스 이미지와 볼륨 설정만 docker-compose.yml에 남기는 모듈화

Override 마법: 로컬 개발 환경에서만 덮어쓰기로 작동하는 docker-compose.override.yml의 암묵적 실행 원리

1단계: 핵심 원인 분석 - 하드코딩의 저주

하나의 파일 안에 MYSQL_ROOT_PASSWORD: my_super_secret 처럼 비밀번호를 박아넣고 깃허브에 푸시하면, 5분 안에 전 세계 해커들의 봇(Bot)이 당신의 DB에 접속해 랜섬웨어를 심고 비트코인을 요구할 것입니다. 또한 운영 서버에서는 Nginx 리버스 프록시 뒤에 숨어야 할 백엔드 서버가 로컬용 설정인 ports: "8080:8080" 때문에 외부로 훌렁 벗겨지는 참사가 생깁니다.

2단계: 완벽한 트러블슈팅 1 - .env 파일로 비밀번호 추출

가장 먼저 모든 패스워드와 환경에 따라 달라지는 변수들을 .env 파일로 뽑아내어 격리해야 합니다. (이 파일은 반드시 .gitignore에 추가하여 깃허브에 안 올라가게 막아야 합니다.)


# 1. 최상단 디렉토리에 .env 파일 생성
DB_PASSWORD=production_secure_password
PORT=8080

# 2. docker-compose.yml 파일 (공통 뼈대)
version: '3.8'
services:
  backend:
    image: my-app:latest
    # 하드코딩 대신 ${변수명} 으로 치환하여 .env 파일의 값을 동적으로 주입
    environment:
      - DB_PASS=${DB_PASSWORD}

3단계: 완벽한 트러블슈팅 2 - Override 파일 자동 병합

개발할 때만 로컬 포트를 외부에 열어주고, 소스코드가 바뀔 때마다 서버가 재시작되도록 마운트(Volume)를 걸어주고 싶을 것입니다. 도커는 docker-compose.override.yml 파일이 폴더에 존재하면, 기본 yml 파일 위에 이 설정들을 **알아서 덮어씌워(Merge)** 실행하는 숨겨진 기능을 제공합니다.


# docker-compose.override.yml (로컬 개발 전용 파일 - 깃허브 제외 권장)
version: '3.8'
services:
  backend:
    # 기본 yml에는 포트가 닫혀있지만, 로컬에서만 8080 포트를 강제로 뚫음
    ports:
      - "8080:8080"
    # 코드를 수정하면 즉시 반영되도록 로컬 폴더를 컨테이너 내부와 연결
    volumes:
      - ./src:/app/src

이 세팅을 마치면 로컬 개발자는 평소처럼 docker-compose up만 쳐도 덮어쓰기 기능이 켜지며 개발 환경이 세팅됩니다. 반면, 운영 서버에는 저 override 파일 자체가 업로드되지 않으므로 가장 안전하고 타이트한 보안 모드로 백엔드가 기동됩니다.

🙋‍♂️ 자주 묻는 질문 (FAQ)

Q. 운영 서버에서도 긴급하게 테스트용 설정 파일을 덮어쓰고 싶으면 어떡하나요?
A. docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d 처럼 -f 옵션을 여러 개 주면, 뒤에 적힌 파일이 앞의 파일을 덮어쓰며 실행됩니다. 환경별로 yml 파일을 여러 개 만들어 두고 CD(지속적 배포) 파이프라인 스크립트에서 이 옵션을 제어하는 것이 엔터프라이즈 정석입니다.

💡 핵심 정리 및 마무리

도커를 쓴다고 무조건 인프라가 안전해지는 것이 아닙니다. 파일 하나에 모든 것을 때려 넣는 모놀리식 사고방식을 버리십시오. 민감한 데이터는 환경변수(.env)로 찢고, 실행 환경의 차이는 Override 파일로 덮어쓰는 다중 계층 보안 아키텍처를 도입하여 해커조차 뚫을 수 없는 무결점 컨테이너 인프라를 지배하시기 바랍니다.

이 블로그 검색

HAGOCUBE | 디지털 생산성 아키텍트