2 / 2
멀티 컨테이너 풀스택 환경 구축과 운영 — Docker Compose 완성하기
대상 도커 기본 명령어와 컨테이너 개념을 익히고 멀티 컨테이너 서비스 구축을 시작하려는 개발자
목표 Docker Compose를 활용해 풀스택 서비스(프론트, 백엔드, DB, Nginx)를 연결하고 개발 및 운영 환경까지 구축한다
완성물 Nginx 프록시, HTTPS 보안, 개발용 라이브 리로드, 운영용 자원 제한 및 백업 스크립트가 적용된
ncafe/시스템
이 따라하기를 진행하려면 아래 도구가 설치되어 있어야 한다.
- Docker Desktop (또는 Docker Engine 및 docker compose plugin)
- mkcert (HTTPS 사설 인증서 생성용)
STEP 1 / 63개 서비스(프론트, 백엔드, DB) 띄우기
0개 완료 · 6개 남음
독립된 3개 컨테이너(Next.js, Spring Boot, PostgreSQL)를 단일 네트워크로 묶는다. DB 준비 상태를 확인 후 백엔드가 실행되도록 순서를 제어하고 환경변수로 비밀번호를 분리한다.
사전준비

상단에 포함된 청부파일을 다운로드 압축을 해재하고 다음 내용을 이어가도록 하자.
1-1. 환경변수 파일 작성
프로젝트 루트 폴더에
.env파일을 만들고 DB 접속 정보를 정의한다.파일:
.envPOSTGRES_DB=ncafedb POSTGRES_USER=ncafeuser POSTGRES_PASSWORD=ncafepassword1231-2. 기본 docker-compose.yml 작성
파일:
docker-compose.ymlversion: '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를 통해 컨테이너 내부 서비스의 실제 준비 상태를 확인하고 부팅 순서를 제어한다.