설치 가이드

허동빈·2026년 1월 27일
Spring bootdocker

docker

목록 보기
8/8
post-thumbnail

🚀 Quick Start Guide - 통합 실행 가이드

Git Clone부터 Docker Compose 실행까지 5분 안에 전체 환경 구축.

1. 사전 준비

✅ 필수 설치 항목 (한 번만)

macOS

# 1. Docker Desktop 설치
# https://www.docker.com/products/docker-desktop/ 에서 다운로드

# 2. 설치 확인
docker --version
docker-compose --version

# 출력 예시:
# Docker version 24.0.0
# Docker Compose version v2.20.0

Windows

# 1. Docker Desktop 설치
# https://www.docker.com/products/docker-desktop/ 에서 다운로드

# 2. WSL 2 활성화 (Docker Desktop이 요구함)
# 설치 중 자동으로 안내됨

# 3. 설치 확인
docker --version
docker-compose --version

🔍 Docker Desktop 실행 확인

macOS: 상단 메뉴바에 고래 아이콘 확인
Windows: 시스템 트레이에 고래 아이콘 확인

2. 프로젝트 실행 (3단계)

📦 Step 1: 코드 받기

🚀 Step 2: Docker Compose 실행

macOS / Windows 공통:

# 전체 스택 시작 (백그라운드)
docker-compose up -d

실행 과정 (3-5분 소요):

[1단계] 이미지 다운로드 (첫 실행 시)
  ✓ MySQL 8.0 이미지 다운로드
  ✓ Redis 7-alpine 이미지 다운로드

[2단계] Spring Boot 빌드
  ✓ Gradle 의존성 다운로드 (60초)
  ✓ bootJar 빌드 (50초)
  ✓ Docker 이미지 생성 (20초)

[3단계] 컨테이너 시작
  ✓ MySQL 시작 및 초기화 (30초)
  ✓ Redis 시작 (5초)
  ✓ Spring Boot 시작 및 BaseInitData 실행 (20초)

✅ 완료!

✅ Step 3: 상태 확인

# 컨테이너 상태 확인
docker-compose ps

# 정상 출력 예시:
# NAME                    STATUS                  PORTS
# auction-app             Up 2 min (healthy)      0.0.0.0:8080->8080/tcp
# auction-mysql-compose   Up 3 min (healthy)      0.0.0.0:3307->3306/tcp
# auction-redis-compose   Up 3 min (healthy)      0.0.0.0:6380->6379/tcp

확인 포인트:

  • ✅ 3개 컨테이너 모두 Up 상태
  • ✅ STATUS에 (healthy) 표시

3. 동작 확인

🧪 API 테스트

# 헬스체크
curl http://localhost:8080/actuator/health

# 정상 응답:
# {"status":"UP"}

🌐 브라우저에서 확인

# Swagger UI (API 문서)
http://localhost:8080/swagger-ui/index.html

# Spring Boot Actuator
http://localhost:8080/actuator/health

📊 초기 데이터 확인

# Spring Boot 로그에서 BaseInitData 실행 확인
docker-compose logs app | grep BaseInitData

# 출력 예시:
# BaseInitData 시작
# 카테고리 12개 생성 완료
# 테스트 유저 3명 생성 완료
# 테스트 경매 20개 생성 완료

🗄️ 데이터베이스 접속 (선택 사항)

MySQL Workbench

Connection Name: Docker Auction App
Hostname: localhost
Port: 3307          ← 중요! (3306 아님)
Username: root
Password: lldj123414
Default Schema: DevCourse

Redis CLI

docker exec -it auction-redis-compose redis-cli

# Redis 명령 실행
127.0.0.1:6379> KEYS *
127.0.0.1:6379> exit

4. 자주 사용하는 명령어

🔄 재시작

# 전체 재시작
docker-compose restart

# Spring Boot만 재시작 (코드 수정 후)
docker-compose restart app

📝 로그 확인

# 전체 로그 (실시간)
docker-compose logs -f

# Spring Boot 로그만 (실시간)
docker-compose logs -f app

# 최근 100줄만 보기
docker-compose logs --tail=100 app

# 에러 로그만 검색
docker-compose logs app | grep ERROR

⏹️ 중지 및 삭제

# 중지 (데이터 유지)
docker-compose stop

# 중지 + 컨테이너 삭제 (데이터 유지)
docker-compose down

# 완전 삭제 (데이터도 삭제)
docker-compose down -v

🔨 코드 수정 후 재배포

# 1. 코드 수정

# 2. Spring Boot만 재빌드 + 재시작
docker-compose build app
docker-compose up -d app

# 또는 한 줄로
docker-compose up -d --build app

📈 리소스 모니터링

# 실시간 리소스 사용량
docker stats

# 한 번만 출력
docker stats --no-stream

5. 트러블슈팅

🐛 문제 1: 컨테이너가 시작 안 됨

증상

docker-compose ps

# 출력:
# auction-app  Restarting (1)

해결

# 1. 로그 확인
docker-compose logs app

# 2. 완전 재시작
docker-compose down
docker-compose up -d

# 3. 캐시 삭제 후 재빌드
docker-compose build --no-cache
docker-compose up -d

🐛 문제 2: 포트 충돌

증상

Error: bind: address already in use

해결

macOS:

# 포트 사용 중인 프로세스 확인
lsof -i :8080
lsof -i :3307
lsof -i :6380

# 프로세스 종료
kill -9 [PID]

Windows (PowerShell):

# 포트 사용 중인 프로세스 확인
netstat -ano | findstr :8080

# 프로세스 종료
taskkill /PID [PID] /F

🐛 문제 3: MySQL 연결 실패

증상

Communications link failure

해결

# MySQL이 healthy 상태가 될 때까지 대기
docker-compose logs -f mysql

# healthy 확인 후 app 재시작
docker-compose restart app

🐛 문제 4: 메모리 부족

증상

docker-compose ps

# 출력:
# auction-app  Restarting (137)  # 137 = OOMKilled

해결

# 1. Docker Desktop 설정에서 메모리 증가
# Docker Desktop → Settings → Resources → Memory: 8GB 이상

# 2. 재시작
docker-compose down
docker-compose up -d

6. 보안 주의사항

⚠️ 개발 환경 vs 운영 환경

현재 설정은 개발/테스트 환경용입니다:

# 개발 환경 설정 (현재)
MYSQL_PASSWORD= ~~~        ← 약한 비밀번호
테스트 유저: ~~~         ← 테스트용

🔒 운영 환경 배포 시 필수 변경

  1. 강력한 비밀번호 설정
# .env 파일 수정
MYSQL_PASSWORD=Strong_P@ssw0rd_2026!
  1. .env 파일 보안
# .gitignore 확인
cat .gitignore | grep .env

# 출력 확인:
# .env
# .env.*
  1. 환경 변수로 민감 정보 관리
# 서버 환경 변수 설정 (운영 환경)
export MYSQL_PASSWORD="운영_비밀번호"
export JWT_SECRET="운영_시크릿키"

🎯 핵심 명령어 요약

시작

# 처음 실행
git clone [레포지토리 URL]
cd DevCource_2
docker-compose up -d

# 확인
docker-compose ps
curl http://localhost:8080/actuator/health

개발 중

# 로그 확인
docker-compose logs -f app

# 코드 수정 후 재배포
docker-compose up -d --build app

# 리소스 모니터링
docker stats

종료

# 중지 (데이터 유지)
docker-compose stop

# 완전 삭제 (다음 실행 시 새로 시작)
docker-compose down -v

💡 FAQ

Q1: 포트를 변경하고 싶어요

A: docker-compose.yml 파일 수정:

services:
  app:
    ports:
      - "9090:8080"  # 호스트 포트를 9090으로 변경

재시작:

docker-compose down
docker-compose up -d

Q2: MySQL/Redis에 직접 접속하려면?

MySQL:

docker exec -it auction-mysql-compose mysql -u root -p
# 비밀번호: lldj123414

Redis:

docker exec -it auction-redis-compose redis-cli

🚨 긴급 문제 해결

모든 것이 안 될 때

# 1. 완전 초기화
docker-compose down -v

# 2. Docker 시스템 정리
docker system prune -a
# 경고: 모든 이미지 삭제됨!

# 3. 재시작
docker-compose up --build -d

# 4. 로그 확인
docker-compose logs -f

📞 도움 요청

문제가 해결되지 않으면:

  1. 로그 수집

    docker-compose logs > error.log

  2. 시스템 정보 수집

    docker version
docker-compose version
docker-compose ps

  3. 팀 리더에게 전달

    • error.log 파일
    • 시스템 정보
    • 실행한 명령어
profile
허동빈
백엔드 공부
이전 포스트

부하 테스트 통합

0개의 댓글