도커 멀티모듈 프로젝트 관리, 내 나름의 정리법

이 글은 제 나름대로 정리하기 위해 작성합니다. 정석방식과는 거리가 멀지도 모릅니다.

멀티모듈 프로젝트를 도커로 관리하다 보면, 도커파일과 환경변수가 서비스별로 여기저기 흩어져서 생각보다 관리가 꽤 복잡해지더군요.
특히 각 서비스 폴더 안에 Dockerfile과 .env가 따로따로 있으면 수정할 때 실수도 잦고, 헷갈리기도 쉽습니다.

그래서 이걸 어떻게 하면 좀 더 깔끔하게, 실수 없이 관리할 수 있을까 고민하다가 지금의 구조와 방식을 사용하게 됐어요

1. 내 프로젝트 구조

프로젝트 루트
├─ a서비스
│   └─ dockerfile
│       ├─ Dockerfile.local
│       ├─ Dockerfile.dev
│       └─ Dockerfile.prod
├─ b서비스
│   └─ dockerfile
│       ├─ Dockerfile.local
│       ├─ Dockerfile.dev
│       └─ Dockerfile.prod
├─ env.local
├─ env.dev
├─ env.prod
├─ docker-compose.local.yml
├─ docker-compose.dev.yml
└─ docker-compose.prod.yml

각 서비스별로 dockerfile 폴더를 만들어 환경(local, dev, prod)에 맞는 도커파일을 분리했고,
환경변수 파일은 루트에 한 곳에 모아서 관리합니다.(서비스 root에 작성해도 되겟지만 보기 안좋더라고요!)

2. 환경변수 주입

도커 이미지를 빌드할 때는 docker build --build-arg 옵션으로 빌드 타임 변수를 넣고,
컨테이너 실행할 땐 environment 옵션으로 런타임 변수를 지정하는 게 일반적이죠.

그런데 서비스별 폴더 안에 각각 .env가 있으면, 도커 컴포즈가 빌드 타임 변수(args)를 주입하기 어려워집니다.
왜냐면 도커 컴포즈는 기본적으로 프로젝트 루트의 .env 파일만 자동으로 인식하기 때문이에요.

즉, 각 서비스 내부 .env는 도커 컴포즈에서 자동으로 읽지 않아서 빌드 시점 변수로 못 쓴다는 얘기죠.

3. 해결 방안

환경변수 파일은 env.local, env.dev, env.prod 이렇게 루트에 한 곳에 모았습니다.
그리고 도커 컴포즈 파일은 각 환경별로 분리해서(docker-compose.local.yml 등) 관리합니다.

4. 실제 도커 컴포즈 설정 예시

services:
  a서비스:
    container_name: a서비스
    image: a서비스registry
    build:
      context: ./a서비스
      dockerfile: dockerfile/Dockerfile.local
      args:
        환경변수1: ${환경변수1}
        환경변수2: ${환경변수2}
    ports:
      - "3000:3000"
    volumes: 
      - ./a서비스:/app
      - /app/node_modules
    environment:
      NODE_ENV: development
      환경변수1: ${환경변수1}
      환경변수2: ${환경변수2}
    depends_on:
      - b서비스
      - c서비스

빌드 시 args에 들어가는 변수들은 env.local 같은 루트 환경변수 파일에서 가져옵니다.

순서도 중요

설정 작성 시, 저는 항목들의 순서를 항상 일정하게 고정해서 관리하려고 노력 합니다.
순서 없이 그때그때 되는 대로 작성하면 지저분해 보이고 헷갈리기도 하더군요.
그래서 규칙을 정해두니 훨씬 깔끔해 보이고, 혼란도 줄일 수 있었습니다.

container_name
image
build 설정
ports
volumes
environment
depends_on

저는 항상 이렇게 정해놓고 작성하고 있어요.

5. 도커 컴포즈 실행 시 환경변수 파일 지정법

도커 컴포즈는 기본적으로 루트의 .env만 자동으로 읽어요.
그래서 env.local, env.dev, env.prod를 사용하려면 직접 지정해줘야 합니다.

docker-compose --env-file env.local -f docker-compose.local.yml up
docker-compose --env-file env.prod -f docker-compose.prod.yml up

이렇게 하면 원하는 환경 변수 파일을 골라서 쓸 수 있습니다.

6. 이렇게 하니 좋은 점

환경변수가 여기저기 흩어져 있지 않고 한 곳에 모여 관리되니 수정하기 편해졌어요.
빌드 시점과 런타임 시점 환경변수를 한눈에 확인할 수 있어서 실수가 줄었습니다.
환경별 전환이 간단해져서 작업 효율이 확실히 올랐습니다.

7. 끝으로

사실 아직도 환경변수 관리 방식에 대해 계속 고민 중입니다.
1번, 루트 폴더에 모든 환경변수를 두는 방법,
2번, 서비스별로 각기 다른 env 파일을 두는 방법,
3번, 루트와 서비스별 env를 조합

AI와 씨름하면 보통 3번 방식을 추천하지만, 저는 아직 효율적으로 활용하지 못하겠더군요.
처음에는 2번 방식으로 가려 했지만, 빌드 시 환경변수 주입이 번거로워서 결국 1번 방식을 선택했습니다.
환경변수를 관리하는 다양한 다른 방법들도 있다고 하는데, 아직 직접 써보지는 못했네요.

좋고 획기적인 방안이 있다면 부디 알려주세요