GitHub Actions + Docker 배포 트러블슈팅: .env 파일이 컨테이너에 들어가지 않는 이유?

🚨  TroubleShotting

문제 발생의 배경 - As Is

프로젝트를 GitHub Actions와 Docker를 활용해 EC2에 배포하는 과정에서, .env 파일이 도커 컨테이너에 정상적으로 들어가지 않는 문제가 발생했다.

단순히 .env 파일 하나의 문제였지만, 이를 해결하는 과정에서 빌드타임과 런타임, 그리고 webpack.config.js에서의 환경변수 처리까지 여러 가지 중요한 개념을 제대로 이해하게 되었다.

이번 글에서는 내가 겪은 문제의 원인과 해결 방법, 그리고 이를 통해 정리한 배포 흐름을 기록해본다.

---

❗️ 문제

•  GitHub Actions에서 .env 파일을 생성하고 EC2에 복사했음에도
• 도커 컨테이너 내부에는 .env 파일이 존재하지 않았음

[ec2-user@ipxxxx ~]$ docker exec -it app cat /usr/src/app/.env
cat: can't open '/usr/src/app/.env': No such file or directory

• 배포된 페이지에서 백엔드로 요청을 할 시, requestUrl 내 API_URL 주소가 undefined가 되어 요청 실패

---

2. 원인 분석

✅ 원인 1. GitHub Actions(deploy.yaml)와 Dockerfile의 실행 흐름에 대한 개념 부족

• deploy.yaml은 GitHub Actions에서 실행되는 YAML 스크립트이고,
  그 중 docker build 단계에서 Dockerfile이 실행됨
• 따라서 .env 파일은 Docker build 이전에 만들어져 있어야 복사 가능함!
• 이전 deploy.yaml 파일에서 .env 생성 명령을 docker build 이전에 했어야 하는데, 이후에 하고 있었음
• 복사할 .env 파일 자체가 없었으므로 - undefined 반환

✅ 원인 2. .dockerignore 파일에 .env가 포함되어 있었음

• .env 파일을 생성해도 Docker 이미지에 복사되지 않음
• 결과적으로 컨테이너 내부에서 .env 파일이 보이지 않음 - undefined 반환

---

2. 해결방안

✅ .dockerignore에서 .env 제외

# .dockerignore
.env  ❌

✅ .env 파일의 2가지 복사 방법

🔧 방법 1. Dockerfile에서 .env를 직접 복사(docker 이미지 빌드 시 복사)

# 1. Build 단계
FROM node:22 AS build
...

# # ✅ .env 파일 추가
# COPY .env ./

...
CMD ["nginx", "-g", "daemon off;"]

🔧 방법 2. EC2에 복사 후 컨테이너로 옮김

이 방법은 .env를 Docker 이미지에 포함하지 않아 보안상으로도 더 안전하지 않을까..? 싶어서 실행해본 방법 🔜 이 방법도 성공!

# deploy.yaml
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
	...
    - name: Prepare .env
        run: |
          # ✅ 1) env 파일 생성
          echo "API_URL=${{ secrets.API_URL }}" > .env 
          echo "📄 .env file contents:"
          cat .env
          ...
 	- name: Copy .env to EC2
        run: |
          # ✅ 2) EC2로 복사
          echo "${{ secrets.EC2_KEY }}" > ec2.pem
          chmod 600 ec2.pem
          scp -i ec2.pem -o StrictHostKeyChecking=no .env ${{ secrets.EC2_USERNAME }}@${{ secrets.EC2_HOST }}:/home/${{ secrets.EC2_USERNAME }}/.env
          
          # ✅ 3) 컨테이너 실행 후 컨테이너 내부 .env 복사할 디렉토리 생성
          docker exec golaping-app mkdir -p /usr/src/app
	
          # ✅ 4) 해당 디렉토리에 EC2의 .env 파일 복사
        docker cp /home/${{ secrets.EC2_USERNAME }}/.env golaping-app:/usr/src/app/.env   
          ...

---

💡 새롭게 알게된 점

빌드타임 vs 런타임 복습

📦  빌드타임	- Webpack이 번들링을 수행할 때, JS 코드가 번들링되고 최종 HTML/JS 파일이 생성되는 시점 - ex) pnpm build 시점  ➡️ 이때 .env 값을 webpack.config.js에서 dotenv로 .env 파일을 읽고,  DefinePlugin으로 process.env.API_URL 같은 값을 실제 JS 코드 내 문자열로 치환
⚙️  런타임	- 웹 브라우저나 Node.js에서 실제 JS 코드가 실행되는 시점 - 앱 내 JS 코드가 실행 중 .env 값을 참조할 때  ➡️ .env 파일이 도커 컨테이너 내부에 존재해야, 실행 코드에서 사용가능하도록 준비됨

---

배포 전체 흐름정리

[GitHub Actions - deploy.yaml]
 1. .env 생성
 2. pnpm build (for 빌드: webpack.config.js 실행 - .env 참조)
 3. docker build (for 런타임: COPY .env ./)
 4. docker push

[EC2]
 5. docker pull
 6. docker run (실행 시 -e API_URL=... 로 전달 가능)

---

🚩마무리

이번 문제는 단순히 .env가 컨테이너에 복사되지 않는 문제였지만,

그 과정에서 빌드타임 vs 런타임의 차이,
GitHub Actions(deploy.yaml)와 Dockerfile의 실행 순서,
webpack에서의 환경변수 주입 방식 등 중요한 개념들을 배울 수 있었다.

이제는 어떤 방식으로 환경변수를 전달할지 선택할 수 있고, 각 방법이 어떤 시점에서 작동하는지도 이해할 수 있게 되었다.