Docker Compose로 웹앱과 데이터베이스 함께 실행

작업 절차 / docker-webapp-db.html

애플리케이션과 PostgreSQL를 한 번에 띄우고 서로 연결하는 절차입니다. 자주 막히는 연결·준비 문제까지 다룹니다.

💬 "웹앱과 DB를 한 번에 띄우고 싶어요 (Docker)"

애플리케이션과 데이터베이스를 각각 따로 설치하지 않고 Docker Compose로 한 번에 띄우는 절차입니다. 가장 자주 막히는 지점(연결이 안 되는 문제)까지 함께 다룹니다.

전제

• Docker와 Compose v2가 설치되어 있습니다 (docker compose version으로 확인)
• 애플리케이션은 8000 포트에서 동작한다고 가정합니다

1단계 — compose 파일 만들기

프로젝트 루트에 compose.yaml을 만듭니다.

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: appdb
    volumes:
      - dbdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 10

  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
    environment:
      DB_HOST: db
      DB_PORT: "5432"
      DB_USER: app
      DB_PASSWORD: app
      DB_NAME: appdb
    ports:
      - "8000:8000"

volumes:
  dbdata:

2단계 — 데이터베이스 접속 정보를 잘못 넣지 않기

가장 흔한 실수는 앱이 localhost로 DB에 접속하려는 것입니다. Compose 안에서 앱 컨테이너가 localhost로 쓰면 그 컨테이너 자신을 가리키게 됩니다.

• DB 호스트에는 localhost가 아니라 서비스 이름(위 예: db)을 씁니다.
• 포트는 호스트에 매핑한 포트(예: 5432가 아닌)가 아니라 DB 컨테이너 안의 포트(5432)를 씁니다.
• Compose는 각 서비스를 프로젝트 네트워크에 붙이고 서비스 이름으로 부르도록 DNS를 제공합니다.

3단계 — 시작과 확인

docker compose up -d
docker compose ps      # 두 서비스가 healthy/running 인지 확인
docker compose logs -f web

4단계 — 앱 시작 시 DB 준비 대기

docker compose up 직후에는 DB가 뜨는 중이라 앱이 먼저 죽을 수 있습니다. 해결 방법은 두 가지입니다.

• Compose의 depends_on: condition: service_healthy로 준비 완료 후 앱을 시작 (위 예제 방식)
• 앱 코드에서 연결 재시도 로직을 넣기 (예: 몇 초 간격으로 몇 회 재시도)

자주 만나는 문제

• Can't reach database server at localhost:5432 → 호스트를 localhost 대신 서비스 이름으로 바꿉니다.
• DB 환경변수(POSTGRES_USER 등)가 무시되는 느낌 → 컨테이너를 재생성해야 합니다. docker compose up -d --force-recreate 또는 볼륨을 비우고 다시 시작합니다. 공식 postgres 이미지는 초기 1회에 한해 변수를 적용합니다.
• 앱 로그에서 relation does not exist → DB는 떴지만 테이블이 아직 없는 상태입니다. 마이그레이션을 실행하세요.

정리 명령

docker compose down        # 컨테이너·네트워크 제거 (볼륨 유지)
docker compose down -v     # 볼륨까지 제거 (DB 데이터 삭제 주의)

검증일은 자료의 최신성을 나타냅니다. 오래된 자료는 적용 조건을 확인하세요.