2026년 Docker Compose로 개발 환경 구축하는 완벽 가이드

• 환경 일관성: 팀원 모두가 똑같은 개발 환경을 가질 수 있어요
• 빠른 시작: 신입 개발자도 10분 안에 개발 환경 세팅 가능해요
• 격리된 환경: 프로젝트마다 다른 버전의 DB를 쓸 수 있죠
• 클린한 로컬: 내 컴퓨터에 직접 설치 안 해도 돼요

1. Docker 공식 사이트에서 Docker Desktop for Windows 다운로드
2. 다운로드한 설치 파일(.exe) 실행
3. 설치 옵션에서 "Use WSL 2 instead of Hyper-V" 체크 (WSL 2가 훨씬 빠르고 안정적이에요)
4. 설치 완료 후 재부팅
5. Docker Desktop 실행해서 설치 확인

docker --version
docker compose version

apt로 설치하는 docker.io 패키지는 버전이 엄청 오래됐어요. Docker 공식 리포지토리를 추가해서 설치하는 게 훨씬 좋습니다.

# 1. 기존 Docker 제거 (있다면)
sudo apt-get remove docker docker-engine docker.io containerd runc

# 2. 필수 패키지 설치
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release

# 3. Docker 공식 GPG 키 추가
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 4. Docker 리포지토리 추가
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. Docker Engine 설치
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 6. 현재 사용자를 docker 그룹에 추가 (sudo 없이 사용)
sudo usermod -aG docker $USER

# 7. 재로그인 또는 다음 명령어 실행
newgrp docker

# 1. 기존 버전 제거
sudo yum remove docker docker-common docker-selinux docker-engine

# 2. 필수 패키지 설치
sudo yum install -y yum-utils

# 3. Docker 리포지토리 추가
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 4. Docker Engine 설치
sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 5. Docker 서비스 시작
sudo systemctl start docker
sudo systemctl enable docker

# 6. 사용자 그룹 추가
sudo usermod -aG docker $USER

# Docker 버전 확인
docker --version

# Docker Compose 버전 확인
docker compose version

# Docker 데몬 상태 확인 (Linux)
sudo systemctl status docker

# 테스트 컨테이너 실행
docker run hello-world

Linux에서 매번 sudo 치는 거 귀찮죠? 현재 사용자를 docker 그룹에 추가하면 sudo 없이도 쓸 수 있어요.

# docker 그룹에 사용자 추가
sudo usermod -aG docker $USER

# 그룹 변경사항 즉시 적용
newgrp docker

# 또는 로그아웃 후 다시 로그인

JSON도 설정 파일로 많이 쓰이잖아요? 근데 YAML이 더 인기 있는 이유는 주석을 쓸 수 있고, 괄호나 쉼표 없이도 깔끔하게 작성할 수 있기 때문이에요. Docker Compose에서는 YAML만 지원하니까 꼭 알아두세요!

VS Code 같은 에디터를 쓰면 탭을 누를 때 자동으로 스페이스로 변환해주는 기능이 있어요. 설정에서 "Tab Size"를 2로 하고, "Insert Spaces"를 켜두는 걸 추천해요. 저도 이렇게 쓰고 있거든요!

name: my-app
version: 3.8
port: 8080
debug: true

ports:
  - 3000:3000
  - 8080:80
  
volumes:
  - ./app:/app
  - ./config:/config

ports: [3000:3000, 8080:80]
tags: [web, frontend, production]

services:
  web:
    image: nginx:latest
    ports:
      - 80:80
    environment:
      NODE_ENV: production
      PORT: 8080
  
  database:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret

# 웹 애플리케이션 서비스
services:
  web:
    image: nginx:latest
    # 외부 포트 80을 컨테이너 포트 80으로 매핑
    ports:
      - 80:80
    # 프로덕션 환경 변수 설정
    environment:
      NODE_ENV: production  # 운영 환경
      DEBUG: false          # 디버그 모드 비활성화

name: my-app
message: "Hello, World!"
path: 'C:\Users\Documents'

description: |
  이것은 여러 줄로 이루어진
  긴 설명입니다.
  줄바꿈이 그대로 유지돼요.

command: >
  이렇게 쓰면
  한 줄로 합쳐집니다.
  긴 명령어 쓸 때 좋아요.

# ❌ 잘못됨
services:
web:
  image:nginx
  ports:
  -80:80

# ✅ 올바름
services:
  web:
    image: nginx
    ports:
      - 80:80

• yamllint.com - 웹에서 바로 검증할 수 있어요
• VS Code YAML 확장 - 에디터에서 실시간 검증이 돼요
• docker-compose config - 터미널에서 docker-compose config 명령어로 확인 가능해요

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - MONGODB_URI=mongodb://mongo:27017/myapp
      - REDIS_URL=redis://redis:6379
    volumes:
      - .:/usr/src/app
      - /usr/src/app/node_modules
    depends_on:
      - mongo
      - redis
    command: npm run dev

  mongo:
    image: mongo:7.0
    ports:
      - "27017:27017"
    environment:
      - MONGO_INITDB_ROOT_USERNAME=admin
      - MONGO_INITDB_ROOT_PASSWORD=secret123
    volumes:
      - mongo-data:/data/db
      - ./mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    command: redis-server --appendonly yes

  mongo-express:
    image: mongo-express:latest
    ports:
      - "8081:8081"
    environment:
      - ME_CONFIG_MONGODB_ADMINUSERNAME=admin
      - ME_CONFIG_MONGODB_ADMINPASSWORD=secret123
      - ME_CONFIG_MONGODB_URL=mongodb://admin:secret123@mongo:27017/
    depends_on:
      - mongo

volumes:
  mongo-data:
  redis-data:

version: '3.8'

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    command: gunicorn config.wsgi:application --bind 0.0.0.0:8000
    volumes:
      - .:/app
      - static_volume:/app/staticfiles
      - media_volume:/app/mediafiles
    expose:
      - 8000
    environment:
      - DEBUG=0
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/myproject
      - ALLOWED_HOSTS=localhost,127.0.0.1
    depends_on:
      - db
      - redis

  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=myproject
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - static_volume:/app/staticfiles
      - media_volume:/app/mediafiles
    ports:
      - "80:80"
    depends_on:
      - web

  celery:
    build: .
    command: celery -A config worker -l info
    volumes:
      - .:/app
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/myproject
      - CELERY_BROKER_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis

  celery-beat:
    build: .
    command: celery -A config beat -l info
    volumes:
      - .:/app
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/myproject
      - CELERY_BROKER_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis

volumes:
  postgres_data:
  redis_data:
  static_volume:
  media_volume:

version: '3.8'

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    environment:
      - REACT_APP_API_URL=http://localhost:8080/api
      - CHOKIDAR_USEPOLLING=true
    stdin_open: true
    tty: true

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      - SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/mydb?useSSL=false&allowPublicKeyRetrieval=true
      - SPRING_DATASOURCE_USERNAME=root
      - SPRING_DATASOURCE_PASSWORD=rootpassword
      - SPRING_JPA_HIBERNATE_DDL_AUTO=update
      - SPRING_PROFILES_ACTIVE=dev
    volumes:
      - ./backend:/app
      - ~/.m2:/root/.m2
    depends_on:
      mysql:
        condition: service_healthy
    command: ./mvnw spring-boot:run

  mysql:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=mydb
      - MYSQL_USER=user
      - MYSQL_PASSWORD=password
    volumes:
      - mysql_data:/var/lib/mysql
      - ./mysql-init:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 20s
      retries: 10

  phpmyadmin:
    image: phpmyadmin:latest
    ports:
      - "8081:80"
    environment:
      - PMA_HOST=mysql
      - PMA_PORT=3306
    depends_on:
      - mysql

volumes:
  mysql_data:

version: '3.8'

services:
  nextjs:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_SUPABASE_URL=${SUPABASE_URL}
      - NEXT_PUBLIC_SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
      - REDIS_URL=redis://redis:6379
      - NODE_ENV=development
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --save 60 1 --loglevel warning

  redis-commander:
    image: rediscommander/redis-commander:latest
    environment:
      - REDIS_HOSTS=local:redis:6379
    ports:
      - "8081:8081"
    depends_on:
      - redis

volumes:
  redis_data:

version: '3.8'

services:
  app:
    build:
      context: .
      target: development
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DEBUG=true
    command: npm run dev

version: '3.8'

services:
  app:
    build:
      context: .
      target: production
    restart: always
    environment:
      - NODE_ENV=production
      - DEBUG=false
    command: npm start
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '1'
          memory: 512M

services:
  # ... 기존 서비스들

  backup:
    image: postgres:16-alpine
    depends_on:
      - db
    volumes:
      - ./backups:/backups
    environment:
      - PGPASSWORD=postgres
    entrypoint: |
      bash -c 'bash -s