Docker

← 목록
2 / 2

멀티 컨테이너 풀스택 환경 구축과 운영 — Docker Compose 완성하기

newlec뉴렉처 공식2026. 10. 26.

대상 도커 기본 명령어와 컨테이너 개념을 익히고 멀티 컨테이너 서비스 구축을 시작하려는 개발자

목표 Docker Compose를 활용해 풀스택 서비스(프론트, 백엔드, DB, Nginx)를 연결하고 개발 및 운영 환경까지 구축한다

완성물 Nginx 프록시, HTTPS 보안, 개발용 라이브 리로드, 운영용 자원 제한 및 백업 스크립트가 적용된 ncafe/ 시스템

이 따라하기를 진행하려면 아래 도구가 설치되어 있어야 한다.

  • Docker Desktop (또는 Docker Engine 및 docker compose plugin)
  • mkcert (HTTPS 사설 인증서 생성용)

STEP 1 / 63개 서비스(프론트, 백엔드, DB) 띄우기

0개 완료 · 6개 남음

  1. 독립된 3개 컨테이너(Next.js, Spring Boot, PostgreSQL)를 단일 네트워크로 묶는다. DB 준비 상태를 확인 후 백엔드가 실행되도록 순서를 제어하고 환경변수로 비밀번호를 분리한다.

    사전준비

    image

    상단에 포함된 청부파일을 다운로드 압축을 해재하고 다음 내용을 이어가도록 하자.

    1-1. 환경변수 파일 작성

    프로젝트 루트 폴더에 .env 파일을 만들고 DB 접속 정보를 정의한다.

    파일: .env

    POSTGRES_DB=ncafedb
    POSTGRES_USER=ncafeuser
    POSTGRES_PASSWORD=ncafepassword123

    1-2. 기본 docker-compose.yml 작성

    파일: docker-compose.yml

    version: '3.8'
    
    services:
      db:
        image: postgres:17
        container_name: ncafe-db
        restart: always
        environment:
          POSTGRES_DB: ${POSTGRES_DB}
          POSTGRES_USER: ${POSTGRES_USER}
          POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
        volumes:
          - postgres_data:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
          interval: 5s
          timeout: 5s
          retries: 5
    
      backend:
        build: ./backend
        container_name: ncafe-backend
        restart: always
        environment:
          SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/${POSTGRES_DB}
          SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER}
          SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
        depends_on:
          db:
            condition: service_healthy
    
      frontend:
        build: ./frontend
        container_name: ncafe-frontend
        restart: always
        environment:
          NEXT_PUBLIC_API_URL: http://backend:8080
        ports:
          - "3000:3000"
        depends_on:
          - backend
    
    volumes:
      postgres_data:

    1-3. 서비스 실행 및 상태 확인

    VSCode 터미널에서 아래 명령을 실행한다.

    docker compose up -d --build

    ✅ 확인

    • docker compose ps 실행 시 3개 컨테이너(ncafe-db, ncafe-backend, ncafe-frontend)의 상태가 모두 running 또는 healthy로 표시된다.

    🎓 newlec 쌤의 코멘트

    단순히 depends_on만 작성하면 DB 컨테이너만 먼저 켜질 뿐, PostgreSQL 프로세스가 포트를 열고 요청을 받을 준비가 되었는지는 보장하지 않는다. 이 때문에 백엔드가 실행 시점에 DB 연결에 실패하며 종료될 수 있다. healthcheck 속성과 condition: service_healthy를 조합해야 완벽한 실행 순서 제어가 가능하다.

    ❌ 자주 하는 실수

    증상 원인 해결
    백엔드 컨테이너가 계속 재시작됨 DB 준비 완료 전에 연결 시도 docker-compose.yml의 healthcheck 조건 및 사용자명 오타 확인
    ${POSTGRES_DB} 값이 적용 안 됨 .env 파일의 위치가 잘못됨 docker-compose.yml과 같은 위치에 .env 파일 작성

    📝 이 단계의 핵심

    • .env 파일을 활용해 중요한 비밀번호와 설정 정보를 소스코드와 분리한다.
    • healthcheck를 통해 컨테이너 내부 서비스의 실제 준비 상태를 확인하고 부팅 순서를 제어한다.

이어지는 내용은 회원만 볼 수 있어요

뉴렉처에 로그인하면 전체 학습 자료를 열람할 수 있습니다.

로그인하기