Docker-Compose on Chanyeol Dev

Docker Compose로 멀티 컨테이너 환경 구축하기: 단계별 튜토리얼

Fri, 24 Apr 2026 00:00:00 +0000

Docker Compose로 멀티 컨테이너 환경 구축하기: 단계별 튜토리얼

주제 키워드: Docker Compose, 멀티 컨테이너, YAML 구성, 의존성 관리, CI/CD 통합

현대 애플리케이션 개발에서 멀티 컨테이너 아키텍처는 마이크로서비스, 데이터 처리 파이프라인, 개발/운영 환경 통합에 필수적인 요소입니다. Docker Compose는 단일 YAML 파일로 여러 컨테이너의 생명주기, 네트워크, 볼륨, 환경 변수를 관리하는 도구로, 개발부터 프로덕션까지 효율성을 극대화합니다. 이 가이드에서는 DB-웹 애플리케이션 예제부터 고급 설정, 트러블슈팅까지 실제 동작 가능한 예제로 설명합니다.

1. Docker Compose의 핵심 개념과 장점

1.1 멀티 컨테이너 아키텍처의 필요성

단일 컨테이너로 모든 기능을 구현하면 관심사 분리가 어렵고, 확장성이 제한됩니다. 예를 들어, 웹 서버와 데이터베이스를 하나의 컨테이너에 묶으면:

DB 업데이트 시 전체 애플리케이션 재빌드 필요
각 서비스의 독립적인 확장(Scale-out) 불가
로깅/모니터링의 복잡성 증가

Docker Compose는 이런 문제를 해결하며, 서비스 간 의존성을 명확히 정의하고 환경별 구성을 쉽게 전환할 수 있습니다. 공식 문서(Docker Compose Overview)에서도 강조하는 핵심 이점은 다음과 같습니다:

선언적 구성: YAML 파일로 인프라 상태를 코드로 관리
의존성 자동 처리: depends_on으로 컨테이너 시작 순서 제어
환경 변수 분리: .env 파일로 민감 정보 관리

1.2 단일 YAML 파일의 효율성

예를 들어, 웹 애플리케이션과 PostgreSQL DB를 연결하는 구성은 다음과 같이 단순화됩니다:

# docker-compose.yml
version: '3.8'
services:
  webapp:
    image: my-webapp:latest
    ports:
      - "8000:8000"
    environment:
      - DB_HOST=db
      - DB_USER=user
      - DB_PASSWORD=secret
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

2. 사전 준비: 개발 환경 설정

2.1 Docker 및 Docker Compose 설치

Linux (Ubuntu 기준):

sudo apt-get update
sudo apt-get install docker.io docker-compose

macOS: Docker Desktop 설치 후 자동 포함
Windows: Docker Desktop 설치 시 WSL2와 함께 Compose 활성화

확인 명령:

docker --version
# Docker version 24.0.2, Build cb71016

docker-compose version
# docker-compose version 1.29.2, build 5becea4c

2.2 네트워크 및 볼륨 개념

네트워크: 컨테이너 간 통신을 위한 가상 네트워크. 기본적으로 Compose는 프로젝트명_default 네트워크를 생성하지만, 커스텀 네트워크도 정의 가능합니다.
볼륨: 호스트와 컨테이너 간 데이터 영구 저장. 위 예제의 postgres_data는 DB 데이터를 호스트에 보관하여 컨테이너 재생성 시에도 데이터 유지

3. 단계별 본문: 기본 구성 실습

3.1 간단한 웹 애플리케이션 예제

Python Flask 애플리케이션과 Redis 캐시를 연동하는 예제를 구현해 보겠습니다.

3.1.1 애플리케이션 코드 작성

# app.py
from flask import Flask
import redis
import os

app = Flask(__name__)
redis_host = os.getenv('REDIS_HOST', 'localhost')
redis_client = redis.StrictRedis(host=redis_host, port=6379, db=0)

@app.route('/')
def hello():
    redis_client.incr('hits')
    return f"Total hits: {redis_client.get('hits').decode('utf-8')"\n
if __name__ == "__main__":
    app.run(host='0.0.0.0', port=8000)

3.1.2 Docker 이미지 빌드

# Dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY . ./
CMD ["python", "app.py"]

# requirements.txt
flask
redis

3.1.3 Docker Compose 파일 작성

# docker-compose.yml
version: '3.8'
services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      REDIS_HOST: redis
    depends_on:
      - redis
  redis:
    image: redis:7.0
    ports:
      - "6379:6379"

3.1.4 실행 및 테스트

# 빌드 및 실행
$ docker-compose up --build

# 별도 터미널에서 테스트
$ curl http://localhost:8000
# 출력: Total hits: 1

3.2 의존성 관리의 중요성

depends_on은 컨테이너 시작 순서만 제어할 뿐, DB 준비 완료 상태를 보장하지 않습니다. 이를 해결하려면 wait-for-it.sh 같은 툴을 사용하거나, 애플리케이션 수준에서 재시도 로직을 구현해야 합니다.

4. 고급 설정: 프로덕션 환경 최적화

4.1 커스텀 네트워크와 환경 변수 분리

4.1.1 네트워크 정의 예제

# docker-compose.yml
version: '3.8'
networks:
  app-network:
    driver: bridge
services:
  web:
    networks:
      - app-network
  db:
    networks:
      - app-network

4.1.2 .env 파일 활용

# .env
DB_USER=admin
DB_PASSWORD=strong_password

# docker-compose.yml
env_file:
  - .env
services:
  web:
    environment:
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}

4.2 프로필 기반 구성 (dev/prod)

Compose 1.27+부터 profiles를 사용해 환경별 서비스를 활성화할 수 있습니다.

# docker-compose.yml
version: '3.8'
services:
  web:
    image: my-webapp:latest
  db:
    image: postgres:15
  devtools:
    image: node:18
    command: npm run dev
    profiles:
      - dev
  monitoring:
    image: prom/prometheus
    profiles:
      - prod

실행 방법:

# 개발 환경
$ docker-compose --profile dev up

# 프로덕션 환경
$ docker-compose --profile prod up

5. 트러블슈팅: 흔한 문제와 해결법

5.1 컨테이너 간 연결 실패

증상: Connection refused 오류 발생
원인: DB가 준비되기 전에 웹 애플리케이션이 연결을 시도
해결:
1. depends_on에 condition 추가
2. Dockerize 같은 툴로 헬스 체크

# 조건 추가 예제
depends_on:
  db:
    condition: service_healthy

5.2 볼륨 마운트 권한 문제

증상: Permission denied 오류
해결:
1. 호스트 디렉터리 권한 변경
2. Docker Compose에서 user 지정

# 권한 문제 해결 예제
volumes:
  - type: volume
    source: myvol
    target: /app/data
    volume:
      nocopy: true

5.3 로그 분석

컨테이너 로그 확인:

$ docker-compose logs [서비스명]
# 예: docker-compose logs web

실시간 모니터링:

$ docker-compose logs -f web

6. 마치며: Docker Compose의 확장성

CI/CD 통합: GitHub Actions, GitLab CI에서 docker-compose 명령어로 테스트 환경 구축 가능
확장성: Kubernetes로의 전환을 위해 Compose 파일을 Helm 차트로 변환 가능
모니터링: Prometheus + Grafana와 연동해 컨테이너 메트릭 수집

추가 학습 자료:

Docker Compose 공식 문서
Awesome Docker 커뮤니티 리소스

이 가이드를 통해 멀티 컨테이너 환경의 설계부터 운영까지의 핵심 역량을 습득할 수 있습니다. 실제 프로덕션 환경에서는 보안 강화(예: TLS 암호화)와 리소스 제한(예: --memory, --cpus)을 추가로 적용해야 합니다.

사내 VM IP 관리 시스템 만들기 - React 대시보드 + Docker Compose 배포 (4편)

Wed, 15 Apr 2026 15:00:00 +0900

React 대시보드

대시보드는 탭 2개로 구성된다.

VM 목록 — 전체 VM 현황, 상태별 필터, ONLINE/OFFLINE/UNKNOWN 배지
이벤트 로그 — IP 충돌, IP 변경, 오프라인 이벤트 타임라인

WebSocket이 아닌 30초 폴링으로 구현했다. VM 상태가 초 단위로 바뀌지 않고, 운영 대시보드 특성상 약간의 지연은 허용된다. 심플하게 가는 게 낫다고 판단했다.

30초 폴링 훅

// usePolling.js
import { useEffect, useRef } from 'react';

export function usePolling(callback, intervalMs = 30_000) {
  const callbackRef = useRef(callback);

  useEffect(() => {
    callbackRef.current = callback;
  });

  useEffect(() => {
    callbackRef.current(); // 마운트 시 즉시 1회 실행

    const id = setInterval(() => callbackRef.current(), intervalMs);
    return () => clearInterval(id);
  }, [intervalMs]);
}

// App.jsx
const [vms, setVms] = useState([]);
const [loading, setLoading] = useState(true);

usePolling(async () => {
  const data = await fetch('/api/vms').then(r => r.json());
  setVms(data);
  setLoading(false);
}, 30_000);

callbackRef를 쓰는 이유는 setInterval 클로저가 최초 등록 시점의 callback을 계속 참조하는 문제를 피하기 위해서다. useRef로 항상 최신 콜백을 가리키도록 한다.

VM 목록 테이블

// VmTable.jsx
const STATUS_BADGE = {
  ONLINE:  { label: 'ONLINE',  className: 'badge-green'  },
  OFFLINE: { label: 'OFFLINE', className: 'badge-red'    },
  UNKNOWN: { label: 'UNKNOWN', className: 'badge-gray'   },
};

export function VmTable({ vms, filter }) {
  const filtered = useMemo(() => {
    return vms.filter(vm => {
      if (filter.status && vm.status !== filter.status) return false;
      if (filter.team && vm.teamId !== filter.team) return false;
      if (filter.search) {
        const q = filter.search.toLowerCase();
        return (
          vm.hostname?.toLowerCase().includes(q) ||
          vm.currentIp?.includes(q)
        );
      }
      return true;
    });
  }, [vms, filter]);

  return (
    <table className="vm-table">
      <thead>
        <tr>
          <th>호스트명th>
          <th>IPth>
          <th>팀th>
          <th>상태th>
          <th>마지막 heartbeatth>
          <th>에이전트 버전th>
        tr>
      thead>
      <tbody>
        {filtered.map(vm => {
          const badge = STATUS_BADGE[vm.status] ?? STATUS_BADGE.UNKNOWN;
          return (
            <tr key={vm.id}>
              <td>{vm.hostname}td>
              <td><code>{vm.currentIp}code>td>
              <td>{vm.teamName ?? '-'}td>
              <td><span className={`badge ${badge.className}`}>{badge.label}span>td>
              <td>{formatRelative(vm.lastSeenAt)}td>
              <td>{vm.agentVersion}td>
            tr>
          );
        })}
      tbody>
    table>
  );
}

이벤트 로그 패널

// EventLogPanel.jsx
const SEVERITY_CLASS = {
  CRITICAL: 'event-critical',
  WARNING:  'event-warning',
  INFO:     'event-info',
};

const EVENT_ICON = {
  IP_CONFLICT:    '🔴',
  IP_CHANGED:     '🔄',
  IP_OUT_OF_RANGE:'⚠️',
  VM_OFFLINE:     '🔴',
  VM_ONLINE:      '🟢',
};

export function EventLogPanel({ events }) {
  return (
    <div className="event-log">
      {events.map(evt => (
        <div key={evt.id} className={`event-item ${SEVERITY_CLASS[evt.severity]}`}>
          <span className="event-icon">{EVENT_ICON[evt.eventType]}span>
          <span className="event-time">{formatDate(evt.createdAt)}span>
          <span className="event-msg">{evt.message}span>
        div>
      ))}
    div>
  );
}

다크/라이트 테마

/* App.css */
:root {
  --bg: #ffffff;
  --surface: #f8f9fa;
  --text: #1a1a1a;
  --border: #e0e0e0;
  --badge-green: #22c55e;
  --badge-red: #ef4444;
  --badge-gray: #9ca3af;
}

[data-theme="dark"] {
  --bg: #0f172a;
  --surface: #1e293b;
  --text: #e2e8f0;
  --border: #334155;
}

// App.jsx
const [theme, setTheme] = useState(
  () => localStorage.getItem('ipam-theme') || 'light'
);

useEffect(() => {
  document.documentElement.setAttribute('data-theme', theme);
  localStorage.setItem('ipam-theme', theme);
}, [theme]);

client nginx 설정

React SPA를 서빙하면서 /api/ 요청을 Spring Boot로 프록시한다.

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location /api/ {
        proxy_pass http://app:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Docker Compose

services:
  postgres:
    image: postgres:16-alpine
    container_name: ipam-postgres
    environment:
      POSTGRES_DB: ipam
      POSTGRES_USER: ipam
      POSTGRES_PASSWORD: ipam1234
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
      - ./sql/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ipam -d ipam"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    container_name: ipam-redis
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  app:
    build: ./backend
    container_name: ipam-app
    ports:
      - "8080:8080"
    environment:
      DB_HOST: postgres
      DB_NAME: ipam
      DB_USER: ipam
      DB_PASS: ipam1234
      REDIS_HOST: redis
      SLACK_WEBHOOK_URL: ${SLACK_WEBHOOK_URL:-}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/actuator/health || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 12
    restart: unless-stopped

  frontend:
    build: ./frontend
    container_name: ipam-frontend
    ports:
      - "3000:80"
    depends_on:
      app:
        condition: service_healthy
    restart: unless-stopped

init.sql을 /docker-entrypoint-initdb.d/에 마운트하면 PostgreSQL 컨테이너 최초 실행 시 자동으로 실행된다. 스키마를 자동으로 생성해주므로 별도로 CREATE TABLE을 실행하지 않아도 된다.

backend Dockerfile

Spring Boot는 빌드가 필요하다. 멀티스테이지 빌드로 최종 이미지에 Maven/JDK 빌드 도구가 포함되지 않도록 한다.

# 빌드 스테이지
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline -q
COPY src ./src
RUN mvn package -DskipTests -q

# 실행 스테이지
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

dependency:go-offline을 먼저 실행해서 Maven 의존성을 레이어로 캐싱한다. 소스 변경 시 의존성 다운로드를 재실행하지 않아서 빌드가 빠르다.

frontend Dockerfile

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --silent
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

배포 명령어

# 환경변수 파일 작성
cat > .env << EOF
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
EOF

# 최초 배포
cd ipam-system
docker compose up -d --build

# 로그 확인
docker logs ipam-app -f
docker logs ipam-frontend -f

# 백엔드만 재배포
docker compose up -d --build app

# 프론트엔드만 재배포
docker compose up -d --build frontend

트러블슈팅

Spring Boot healthcheck curl 없음

eclipse-temurin:21-jre-alpine에는 curl이 없어서 CMD curl -f ...가 실패했다.

# 실패
test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]

# 해결: CMD-SHELL로 변경 (sh -c 경유)
test: ["CMD-SHELL", "curl -f http://localhost:8080/actuator/health || exit 1"]

alpine 이미지에는 sh가 있어서 CMD-SHELL을 쓰면 sh를 통해 명령이 실행된다. curl 설치를 Dockerfile에 추가하거나, wget이 있다면 wget으로 대체하는 방법도 있다.

Spring Boot 시작 시간 + healthcheck

Spring Boot가 완전히 뜨기까지 20~30초 걸린다. retries: 12, interval: 10s로 설정해서 최대 2분을 대기한다. 이 시간 안에 spring이 안 뜨면 컨테이너가 unhealthy로 전환된다.

init.sql 재실행 안 됨

PostgreSQL 컨테이너는 /var/lib/postgresql/data가 비어있을 때만 initdb를 실행한다. 볼륨이 남아있으면 init.sql이 재실행되지 않는다. 스키마를 수동 적용하거나 볼륨을 삭제해야 한다.

# 볼륨 삭제 후 재시작 (데이터 초기화 주의)
docker compose down -v
docker compose up -d --build

마무리

4편에 걸쳐 IPAM VM 관리 시스템을 만든 과정을 정리했다.

편	내용
1편	기획 배경 + 전체 아키텍처 + DB 스키마
2편	Node.js 에이전트 → Go 에이전트 전환
3편	Spring Boot Heartbeat 처리 + 이상 감지 + Slack 알림
4편	React 대시보드 + Docker Compose 배포 ← 지금 여기

핵심은 두 가지다.

MAC 주소 기반 VM 식별 — IP는 바뀌지만 MAC은 고정이다. IP를 기준으로 삼으면 VM이 IP를 바꿀 때마다 새 VM으로 등록되는 문제가 생긴다.

에이전트는 최대한 가볍게 — Go 단일 바이너리 6 MB로 Node.js 45 MB 대비 크기를 87% 줄였다. 배포하기 쉬울수록 VM이 늘어나도 관리가 편하다.

현재 인사정보 시스템과 연동해서 VM 담당자가 퇴사했을 때 자동으로 알림이 오는 흐름을 구성할 예정이다.

사내 인사정보 관리 시스템 만들기 - Docker Compose 멀티 서비스 배포 + 트러블슈팅 (3편)

Sat, 11 Apr 2026 13:00:00 +0900

Docker Compose 멀티 서비스 구성

세 서비스가 올바른 순서로 떠야 한다.

db (PostgreSQL) → server (Express + Prisma) → client (React + nginx)

server가 DB보다 먼저 뜨면 Prisma 연결이 실패하고, client가 server보다 먼저 뜨면 API 프록시가 동작하지 않는다.

docker-compose.yml

services:
  db:
    image: postgres:16-alpine
    container_name: insa-db
    environment:
      POSTGRES_DB: unipost_insa
      POSTGRES_USER: insa
      POSTGRES_PASSWORD: insa1234
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U insa -d unipost_insa"]
      interval: 5s
      timeout: 5s
      retries: 10

  server:
    build: ./server
    container_name: insa-server
    ports:
      - "4000:4000"
    env_file:
      - ./server/.env
    environment:
      DATABASE_URL: postgresql://insa:insa1234@db:5432/unipost_insa
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "node", "-e",
        "require('http').get('http://localhost:4000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  client:
    build: ./client
    container_name: insa-client
    ports:
      - "3002:80"
    depends_on:
      server:
        condition: service_healthy
    restart: unless-stopped

depends_on에 condition: service_healthy를 쓰면 단순히 컨테이너가 “시작됐는지"가 아니라 “준비됐는지"를 확인하고 다음 서비스를 시작한다.

DB healthcheck

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U insa -d unipost_insa"]
  interval: 5s
  timeout: 5s
  retries: 10

pg_isready는 PostgreSQL이 연결을 받을 준비가 됐는지 확인하는 내장 커맨드다. 컨테이너가 떠도 PostgreSQL 프로세스가 완전히 초기화되기까지 몇 초 걸리기 때문에 이 healthcheck가 없으면 server가 너무 일찍 연결을 시도해서 실패한다.

server healthcheck — wget/curl 없을 때

server healthcheck에서 문제가 생겼다. node:20-slim 이미지에는 wget과 curl이 설치되어 있지 않아서 일반적인 HTTP healthcheck 방법이 안 된다.

# 이건 안 됨 (wget 없음)
test: ["CMD", "wget", "-q", "--spider", "http://localhost:4000/health"]

해결: Node.js 내장 http 모듈로 대체한다.

healthcheck:
  test: ["CMD", "node", "-e",
    "require('http').get('http://localhost:4000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
  interval: 5s
  timeout: 5s
  retries: 10

/health 엔드포인트가 200을 반환하면 process.exit(0) (성공), 아니면 process.exit(1) (실패)로 healthcheck 결과를 전달한다.

서버에 /health 엔드포인트를 추가해둔다.

app.get('/health', (req, res) => res.sendStatus(200));

entrypoint.sh — DB 대기 + Prisma 자동 마이그레이션

server Dockerfile에서 entrypoint.sh를 실행 진입점으로 쓴다.

#!/bin/sh
set -e

echo "DB 연결 대기 중..."
until npx prisma db push --skip-generate 2>/dev/null; do
  echo "DB 아직 준비 안 됨, 재시도..."
  sleep 2
done

echo "DB 준비 완료, 서버 시작"
exec node src/index.js

prisma db push는 스키마와 DB를 동기화한다. DB가 아직 준비 안 됐으면 실패하고, 성공할 때까지 2초마다 재시도한다.

healthcheck + depends_on이 있어도 이 루프를 유지하는 게 좋다. healthcheck 타이밍이 맞지 않는 엣지 케이스가 간혹 있기 때문이다.

server Dockerfile

FROM node:20-slim
RUN apt-get update && apt-get install -y openssl && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY prisma ./prisma
RUN npx prisma generate
COPY src ./src
COPY entrypoint.sh ./
RUN chmod +x entrypoint.sh
EXPOSE 4000
ENTRYPOINT ["./entrypoint.sh"]

openssl 설치가 빠지면 안 된다. 트러블슈팅에서 다룬다.

client nginx 설정

React SPA를 서빙하면서 /api/ 요청은 server로 프록시한다.

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    # API 요청 → server 컨테이너로 프록시
    location /api/ {
        proxy_pass http://server:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # SPA 라우팅 (새로고침 시 404 방지)
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Docker Compose 내부 네트워크에서는 서비스 이름으로 통신할 수 있다. http://server:4000처럼 쓰면 된다.

client .env

VITE_API_URL=/api

Vite 빌드 시 API URL을 /api로 설정해두면 nginx가 알아서 server로 프록시한다. 서버 IP를 하드코딩할 필요가 없다.

client Dockerfile

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --silent
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

멀티스테이지 빌드로 최종 이미지에 node, npm이 포함되지 않는다.

배포 명령어

# 최초 배포
cd unipost_insa
docker compose up -d --build

# 최초 데이터 수집 (배치 수동 실행)
docker exec insa-server node -e "require('./src/batch').runBatch().catch(console.error)"

# 서버 코드 변경 후
docker compose up -d --build server

# 클라이언트 변경 후
docker compose up -d --build client

# 로그 확인
docker logs insa-server -f
docker logs insa-client -f

로컬 개발 (Docker 없이)

# DB만 Docker로 띄우기
docker compose up -d db

# 서버
cd server
npm install
npx prisma db push
npm run dev   # localhost:4000

# 클라이언트 (새 터미널)
cd client
npm install
npm run dev   # localhost:5173

트러블슈팅

Prisma + Alpine OpenSSL 오류

Error: Unable to require('node_modules/.prisma/client/libquery_engine-linux-musl.so.node')
PrismaClientInitializationError: Unable to open the libssl.so.1.1 file.

node:20-alpine은 musl libc 기반이라 Prisma가 요구하는 OpenSSL 버전과 맞지 않는다.

해결: node:20-slim(Debian 기반)으로 변경하고 OpenSSL을 명시적으로 설치한다.

FROM node:20-slim
RUN apt-get update && apt-get install -y openssl && rm -rf /var/lib/apt/lists/*

schema.prisma에도 binaryTargets를 추가해야 한다.

generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "debian-openssl-3.0.x"]
}

Docker 시작 순서 문제

depends_on만 써도 순서는 보장되지만, 이건 컨테이너가 “시작됐는지"만 확인한다. PostgreSQL이 실제로 연결을 받을 준비가 되기 전에 server가 연결을 시도하면 실패한다.

# 이것만으론 부족
depends_on:
  - db

# 이렇게 해야 함
depends_on:
  db:
    condition: service_healthy

service_healthy는 healthcheck가 통과한 후에 다음 서비스를 시작한다.

server healthcheck wget/curl 없음

위에서 다룬 것처럼 node:20-slim에는 wget/curl이 없다.

# Node.js 내장 http로 대체
test: ["CMD", "node", "-e",
  "require('http').get('http://localhost:4000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]

AG Grid v33 테마 충돌

2편에서 다뤘지만 배포 후에도 동일하게 적용해야 한다.

<AgGridReact theme="legacy" ... />

인사 API 빈 배열 반환

배치를 돌렸는데 API 응답: 0명이 나오는 경우가 있었다. Request Body 없이 호출하면 빈 배열을 반환하는 API 특성 때문이었다. 파라미터를 명시적으로 넘겨줘야 전체 인원이 조회된다.

마무리

3편에 걸쳐 인사정보 관리 시스템을 만든 과정을 정리했다.

편	내용
1편	아키텍처 + Prisma 스키마 설계
2편	배치 변동 감지 + React AG Grid UI
3편	Docker Compose 멀티 서비스 배포 + 트러블슈팅 ← 지금 여기

핵심은 시작 순서 보장이다. healthcheck + depends_on condition: service_healthy + entrypoint.sh 재시도 루프, 세 가지를 같이 써야 안정적으로 동작한다.

향후 이 시스템에서 감지한 입퇴사·부서이동 변동을 Slack 알림 봇과 연동해서 자동으로 알림이 오도록 구성할 예정이다.