Docker Compose로 개인 프로젝트 배포할 때 자주 하는 실수

Docker Compose는 개인 프로젝트를 배포할 때 정말 편합니다. compose.yml 하나에 앱, 데이터베이스, 리버스 프록시 설정을 모아둘 수 있고, 서버에서는 docker compose up -d만 실행하면 됩니다.

하지만 편한 만큼 실수도 자주 합니다. 저도 처음에는 컨테이너가 실행됐다는 것만 보고 배포가 끝났다고 생각했는데, 실제로는 환경변수가 빠져 있거나 포트가 잘못 연결된 경우가 있었습니다.

1. 포트 매핑을 헷갈리는 실수

Compose에서 포트는 보통 이런 형태로 씁니다.

ports:
  - "3000:3000"

왼쪽은 서버에서 열리는 포트이고, 오른쪽은 컨테이너 내부 포트입니다.

예를 들어 앱이 컨테이너 안에서 3000번으로 실행되는데 서버에서는 8080번으로 열고 싶다면 이렇게 써야 합니다.

ports:
  - "8080:3000"

접속이 안 될 때는 먼저 실제 포트가 열려 있는지 확인합니다.

ss -tulpn | grep 8080

2. 환경변수 파일을 서버에 안 올리는 실수

로컬에서는 .env가 있어서 잘 되는데 서버에서는 실패하는 경우가 많습니다.

env_file:
  - .env

이렇게 설정했다면 서버에도 .env 파일이 있어야 합니다. 단, .env에는 비밀번호나 토큰이 들어가므로 Git에 올리면 안 됩니다.

배포할 때는 서버에서 직접 만들거나, 안전한 방식으로 복사해야 합니다.

nano .env

컨테이너 안에서 환경변수가 들어갔는지 확인하고 싶다면 다음 명령어를 사용할 수 있습니다.

docker compose exec app env

3. 볼륨 위치를 생각하지 않는 실수

데이터베이스나 업로드 파일을 컨테이너 내부에만 저장하면 컨테이너를 지웠을 때 데이터가 사라질 수 있습니다.

volumes:
  - ./data:/app/data

이런 식으로 호스트 디렉터리에 연결해두면 데이터가 서버 파일시스템에 남습니다.

데이터베이스는 named volume을 쓰는 경우도 많습니다.

volumes:
  db_data:

그리고 서비스에 연결합니다.

services:
  db:
    volumes:
      - db_data:/var/lib/postgresql/data

4. 로그를 안 보고 재시작만 하는 실수

컨테이너가 죽으면 무작정 다시 실행하기보다 로그를 먼저 봐야 합니다.

docker compose logs -f app

로그에 connection refused, missing env, permission denied 같은 메시지가 있으면 원인을 바로 좁힐 수 있습니다.

실행 상태는 이렇게 확인합니다.

docker compose ps

5. 이미지 재빌드를 깜빡하는 실수

코드를 바꿨는데 이전 이미지가 계속 실행되는 경우도 있습니다.

docker compose up -d --build

캐시 문제까지 의심된다면 빌드 캐시를 끄고 다시 빌드할 수 있습니다.

docker compose build --no-cache

마무리 체크리스트

Docker Compose로 배포할 때는 최소한 이것만 확인합니다.

• 포트 매핑이 맞는지
• .env가 서버에 있는지
• 볼륨이 필요한 데이터에 연결되어 있는지
• docker compose logs로 에러를 봤는지
• 코드 수정 후 이미지를 다시 빌드했는지

Compose는 간단하지만, 배포 문제의 대부분은 작은 설정 실수에서 시작됩니다. 그래서 배포가 끝난 뒤에는 “컨테이너가 켜졌다”에서 멈추지 말고 실제 접속과 로그까지 확인하는 게 좋습니다.