Docker Compose

Docker Compose는 여러 컨테이너로 구성된 애플리케이션을 하나의 YAML 파일(docker-compose.yml)로 정의하고, 단일 명령어로 실행·관리하는 도구이다. 웹 서버 + 애플리케이션 + 데이터베이스처럼 여러 서비스가 함께 동작하는 환경을 구성할 때 특히 유용하다.

# docker run 방식 — 명령어 3개를 순서대로 직접 실행
docker network create app-net
docker volume create db-data

docker run -d --name db --network app-net \
  -e MYSQL_ROOT_PASSWORD=secret -e MYSQL_DATABASE=visitdb \
  -v db-data:/var/lib/mysql mysql:8.4

docker run -d --name app --network app-net \
  -e SPRING_DATASOURCE_URL=jdbc:mysql://db:3306/visitdb \
  visit-counter:1.0

docker run -d --name nginx --network app-net \
  -p 80:80 -v ./nginx.conf:/etc/nginx/conf.d/default.conf \
  nginx:1.30

docker compose up -d

#1. 기본 개념

#2. docker-compose.yml 작성

#2-1. 파일 기본 구조

services:
  서비스명1:
    # 서비스 설정
  서비스명2:
    # 서비스 설정

networks:
  # 네트워크 설정 (선택)

volumes:
  # 볼륨 설정 (선택)

secrets:
  # 시크릿 설정 (선택)

#2-2. 주요 옵션 설명

image — 사용할 이미지 지정

services:
  db:
    image: mysql:8.4

build — Dockerfile로 이미지 직접 빌드

services:
  app:
    build:
      context: ./app
      dockerfile: Dockerfile

ports — 무엇을 외부에 열 것인가

services:
  nginx:
    image: nginx:1.30
    ports:
      - "80:80"       # 호스트 80 → 컨테이너 80 (외부에서 접근 가능)

  app:
    build: ./app
    # ports 없음 → 호스트에 발행되지 않아 외부에서 직접 접근할 수 없다.
    # 같은 네트워크의 nginx 는 http://app:8080 으로 접근한다.

environment — 환경 변수 직접 설정 (개발 환경용)

services:
  db:
    environment:
      MYSQL_DATABASE: visitdb
      MYSQL_USER: visituser
      # 비밀번호는 직접 넣지 않는다 → env_file 또는 secrets 사용

env_file — 환경 변수를 파일에서 로드

services:
  db:
    env_file:
      - .env    # .env 파일의 모든 변수를 환경 변수로 주입

level=warning msg="The \"MYSQL_DATABASE\" variable is not set. Defaulting to a blank string."

secrets — 민감한 값을 파일로 안전하게 관리

services:
  db:
    secrets:
      - mysql_root_password     # /run/secrets/mysql_root_password 로 마운트됨
    environment:
      MYSQL_ROOT_PASSWORD_FILE: /run/secrets/mysql_root_password

secrets:
  mysql_root_password:
    file: ./secrets/mysql_root_password.txt   # 실제 값이 담긴 파일

volumes — 볼륨 또는 디렉토리 마운트

services:
  nginx:
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro  # 읽기 전용 바인드 마운트
  db:
    volumes:
      - db-data:/var/lib/mysql   # Named Volume

restart — 컨테이너 재시작 정책

depends_on — 서비스 시작 순서 + 준비 상태 대기

services:
  app:
    depends_on:
      db:
        condition: service_healthy   # DB 헬스체크 통과 후 app 시작
  db:
    image: mysql:8.4
    healthcheck:
      # -h 127.0.0.1 로 TCP 를 확인한다. localhost 로 하면 아래 경고의 함정에 걸린다.
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 40s

healthcheck — 서비스 준비 상태 체크

services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 15s       # 체크 간격
      timeout: 5s         # 타임아웃
      retries: 5          # 실패 허용 횟수
      start_period: 30s   # 기동 유예 시간 (이 시간 동안은 실패해도 unhealthy 아님)

#3. docker compose 명령어

#4. 종합 실습 — Nginx + Spring Boot + MySQL 3-tier 구성

단순 Nginx + DB 조합을 넘어, 실무에 가까운 3-tier 구조를 직접 구성한다.

#최종 아키텍처

[브라우저]
    ↓ :80  (유일하게 외부에 열린 포트)
┌──────────────────────────────┐
│  nginx  (리버스 프록시)        │
│  - 정적 파일 직접 서빙         │
│  - / → app:8080 프록시        │
└──────────────┬───────────────┘
               ↓ :8080  (내부 네트워크 전용)
┌──────────────────────────────┐
│  visit-counter  (Spring Boot) │
│  - MySQL에 방문 횟수 저장      │
└──────────────┬───────────────┘
               ↓ :3306  (내부 네트워크 전용)
┌──────────────────────────────┐
│  db  (MySQL 8.4)              │
│  - 패스워드: Docker Secrets   │
└──────────────────────────────┘

#Step 0. 프로젝트 구조 준비

visit-counter-compose/
├── docker-compose.yml
├── .env                          ← Git 제외 (실제 비밀값)
├── .env.example                  ← Git 포함 (키 이름만, 신규 팀원 온보딩용)
├── .gitignore
├── secrets/
│   ├── mysql_root_password.txt   ← Docker Secrets 파일
│   └── mysql_user_password.txt
├── nginx/
│   └── nginx.conf
└── app/                          ← visit-counter 앱 (MySQL 연동)
    ├── build.gradle
    ├── settings.gradle
    ├── Dockerfile
    ├── docker-entrypoint.sh   ← Secrets 를 환경변수로 넘기는 스크립트
    └── src/main/
        ├── java/com/example/
        │   ├── VisitCounterApplication.java
        │   ├── VisitCount.java
        │   └── VisitCountRepository.java
        └── resources/
            └── application.yml

# 디렉토리 생성 (macOS / Linux / WSL / Git Bash)
mkdir -p visit-counter-compose/{secrets,nginx,app/src/main/{java/com/example,resources}}
cd visit-counter-compose

# Windows PowerShell — 중괄호 확장이 없으므로 경로를 하나씩 적는다
"secrets","nginx","app/src/main/java/com/example","app/src/main/resources" |
  ForEach-Object { New-Item -ItemType Directory -Force -Path "visit-counter-compose/$_" | Out-Null }
cd visit-counter-compose

#Step 1. 비밀값 파일 준비

secrets/ 파일 생성

echo 'RootPassword!123' > secrets/mysql_root_password.txt
echo 'UserPassword!456' > secrets/mysql_user_password.txt

# Windows PowerShell — echo 와 > 를 쓰지 않는다 (아래 경고 참고)
Set-Content -Path secrets/mysql_root_password.txt -Value 'RootPassword!123' -NoNewline -Encoding ascii
Set-Content -Path secrets/mysql_user_password.txt -Value 'UserPassword!456' -NoNewline -Encoding ascii

echo 'Ab!1' > a.txt            →  FF FE 41 00 62 00 21 00 31 00 0D 00 0A 00
Set-Content ... -Encoding ascii →  41 62 21 31

bash: !123: event not found

# 파일이 제대로 만들어졌는지 확인
cat secrets/mysql_root_password.txt
# RootPassword!123

.env 파일 작성 — Git에 절대 커밋 금지

# .env
MYSQL_DATABASE=visitdb
MYSQL_USER=visituser

.env.example 파일 작성 — Git에 포함, 신규 팀원 온보딩용

# .env.example
MYSQL_DATABASE=visitdb
MYSQL_USER=visituser

.gitignore 작성

# .gitignore
.env
secrets/

#Step 2. Spring Boot 앱 코드 (MySQL 연동)

visit-counter의 카운트를 MySQL DB에 저장하도록 확장한다.

app/settings.gradle

rootProject.name = 'visit-counter'

ERROR: failed to calculate checksum of ref ...: "/settings.gradle": not found

app/build.gradle

plugins {
    id 'org.springframework.boot' version '4.1.1'
    id 'io.spring.dependency-management' version '1.1.7'
    id 'java'
}

group = 'com.example'
version = '1.0.0'
java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    runtimeOnly 'com.mysql:mysql-connector-j'
}

app/src/main/resources/application.yml

spring:
  datasource:
    url: ${SPRING_DATASOURCE_URL}
    username: ${SPRING_DATASOURCE_USERNAME}
    password: ${SPRING_DATASOURCE_PASSWORD}   # 환경변수로 주입받음 (아래 참고)
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false

server:
  port: 8080

VisitCount.java — JPA 엔티티

package com.example;

import jakarta.persistence.*;
import java.time.LocalDateTime;

@Entity
@Table(name = "visit_count")
public class VisitCount {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private long count = 0;

    private LocalDateTime updatedAt = LocalDateTime.now();

    public long getCount() { return count; }
    public void setCount(long count) {
        this.count = count;
        this.updatedAt = LocalDateTime.now();
    }
}

VisitCountRepository.java

package com.example;

import org.springframework.data.jpa.repository.JpaRepository;

public interface VisitCountRepository extends JpaRepository<VisitCount, Long> {}

VisitCounterApplication.java

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
@RestController
public class VisitCounterApplication {

    private final VisitCountRepository repo;

    public VisitCounterApplication(VisitCountRepository repo) {
        this.repo = repo;
    }

    public static void main(String[] args) {
        SpringApplication.run(VisitCounterApplication.class, args);
    }

    @GetMapping("/")
    public String visit() {
        VisitCount vc = repo.findAll().stream().findFirst()
            .orElseGet(() -> { VisitCount v = new VisitCount(); return repo.save(v); });
        vc.setCount(vc.getCount() + 1);
        repo.save(vc);
        return "방문 횟수: " + vc.getCount() + "\n";
    }

    @GetMapping("/count")
    public String count() {
        long c = repo.findAll().stream().findFirst()
            .map(v -> v.getCount()).orElse(0L);
        return "현재 카운트: " + c + "\n";
    }

    @GetMapping("/reset")
    public String reset() {
        repo.findAll().stream().findFirst().ifPresent(v -> {
            v.setCount(0); repo.save(v);
        });
        return "카운터를 초기화했습니다.\n";
    }
}

app/Dockerfile (멀티 스테이지 빌드 + Secrets 지원)

# ── 1단계: Gradle로 JAR 빌드 ──────────────────────────────
FROM gradle:8.14-jdk21 AS builder
WORKDIR /build
# 의존성 먼저, 소스는 나중에 — 이미지 생성 및 관리 장 6-4 의 캐시 구조
COPY settings.gradle build.gradle ./
RUN gradle dependencies --no-daemon > /dev/null
COPY src ./src
RUN gradle bootJar --no-daemon

# ── 2단계: JRE만 포함한 경량 실행 이미지 ─────────────────
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /build/build/libs/visit-counter-1.0.0.jar app.jar

# Secrets 파일을 읽어 환경변수로 변환하는 엔트리포인트 스크립트
COPY docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh

# 애플리케이션은 root 가 아닌 전용 계정으로 돌린다
RUN groupadd --system app && useradd --system --gid app --no-create-home app
USER app

EXPOSE 8080
ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["java", "-jar", "app.jar"]

app/docker-entrypoint.sh

#!/bin/sh
# Docker Secrets는 /run/secrets/<파일명> 형태로 마운트됨
# Spring Boot는 _FILE 접미사를 기본 지원하지 않으므로
# 파일을 읽어 SPRING_DATASOURCE_PASSWORD 환경변수에 직접 주입한다

if [ -f /run/secrets/mysql_user_password ]; then
  export SPRING_DATASOURCE_PASSWORD=$(cat /run/secrets/mysql_user_password)
fi

# 전달받은 CMD 실행 (java -jar app.jar)
exec "$@"

exec /docker-entrypoint.sh: no such file or directory

*.sh text eol=lf

docker compose exec app sh -c 'tr "\0" "\n" < /proc/1/environ | grep PASSWORD'
# SPRING_DATASOURCE_PASSWORD=UserPassword!456

spring:
  config:
    import: optional:configtree:/run/secrets/

#Step 3. Nginx 리버스 프록시 설정

nginx/nginx.conf

upstream app {
    server app:8080;   # 서비스 이름으로 접근 (내부 DNS)
}

server {
    listen 80;

    # Spring Boot 앱으로 프록시
    location / {
        proxy_pass         http://app;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

#Step 4. docker-compose.yml 완성

services:

  # ── Nginx : 유일하게 외부에 열린 포트 ───────────────────
  nginx:
    image: nginx:1.30
    ports:
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      app:
        condition: service_healthy    # 앱 헬스체크 통과 후 시작
    restart: unless-stopped

  # ── Spring Boot 앱 ───────────────────────────────────────
  app:
    build:
      context: ./app
    # ports 없음 → 외부 미노출. nginx 가 http://app:8080 으로 접근한다.
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://db:3306/${MYSQL_DATABASE}
      SPRING_DATASOURCE_USERNAME: ${MYSQL_USER}
      # SPRING_DATASOURCE_PASSWORD 는 entrypoint 스크립트가 Secrets 파일에서 읽어 주입
    secrets:
      - mysql_user_password
    depends_on:
      db:
        condition: service_healthy    # DB 헬스체크 통과 후 시작
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 40s               # Spring Boot 기동 시간 여유
    restart: unless-stopped

  # ── MySQL ────────────────────────────────────────────────
  db:
    image: mysql:8.4
    # ports 없음 → 외부 미노출 (보안)
    env_file:
      - .env                          # MYSQL_DATABASE, MYSQL_USER 주입
    environment:
      MYSQL_ROOT_PASSWORD_FILE: /run/secrets/mysql_root_password
      MYSQL_PASSWORD_FILE: /run/secrets/mysql_user_password
    secrets:
      - mysql_root_password
      - mysql_user_password
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      # -h 127.0.0.1 로 TCP 를 확인한다. localhost 로 하면 아래 경고의 함정에 걸린다.
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 40s
    restart: unless-stopped

volumes:
  db-data:

secrets:
  mysql_root_password:
    file: ./secrets/mysql_root_password.txt
  mysql_user_password:
    file: ./secrets/mysql_user_password.txt

Authentication plugin 'mysql_native_password' cannot be loaded

  db:
    image: mysql:8.4
    command: --mysql-native-password=ON

#Step 5. 실행 및 헬스체크 흐름 확인

# 빌드 + 백그라운드 실행
docker compose up -d --build

# 서비스 상태 확인 (healthy가 될 때까지 관찰)
docker compose ps

# 예상 출력 (NAME / STATUS / PORTS 만 발췌 — 실제로는 아래 설명의 컬럼이 모두 나온다):
# NAME                            STATUS                   PORTS
# visit-counter-compose-db-1      Up 33 seconds (healthy)  3306/tcp, 33060/tcp
# visit-counter-compose-app-1     Up 12 seconds (healthy)  8080/tcp
# visit-counter-compose-nginx-1   Up 2 seconds             0.0.0.0:80->80/tcp, [::]:80->80/tcp

서비스 시작 순서가 자동으로 제어된다.

db 시작 → healthcheck 통과 →
app 시작 → healthcheck 통과 →
nginx 시작

# 각 서비스 로그로 시작 순서 확인
docker compose logs --timestamps

#Step 6. 동작 및 보안 검증

접속 테스트

# Nginx를 통해 정상 접근
curl http://localhost/          # 방문 횟수: 1
curl http://localhost/          # 방문 횟수: 2
curl http://localhost/count     # 현재 카운트: 2

# 앱 포트 직접 접근 — 실패해야 정상
curl http://localhost:8080      # Connection refused (외부 미노출)

# DB 포트 직접 접근 — 실패해야 정상
curl http://localhost:3306      # Connection refused (외부 미노출)

80 포트(Nginx)로만 접근할 수 있다 — 앱의 8080은 외부에 열려 있지 않다

/actuator/health 가 UP 이어야 Nginx가 기동된다

Secrets 보안 검증 — docker inspect로 비밀번호 노출 여부 확인

# 환경변수 방식이었다면 Env 목록에 비밀번호가 노출되었을 것
docker inspect $(docker compose ps -q app | head -1) | grep -A 20 '"Env"'
# [
#   "SPRING_DATASOURCE_URL=jdbc:mysql://db:3306/visitdb",
#   "SPRING_DATASOURCE_USERNAME=visituser",
#   ...   ← 비밀번호가 환경변수에 없음
# ]

# Secrets로 마운트된 파일 내용은 컨테이너 내부에서만 접근 가능
docker compose exec app cat /run/secrets/mysql_user_password
# UserPassword!456

cat: 'C:/Program Files/Git/run/secrets/mysql_user_password': No such file or directory

docker compose exec app cat //run/secrets/mysql_user_password

#Step 7. 설정 검증 — docker compose config

# .env 변수와 secrets 경로가 올바르게 치환됐는지 확인
docker compose config

# 특정 서비스 설정만 확인
docker compose config --services
# nginx
# app
# db

# 환경변수 치환 결과 확인 (비밀번호 값은 _FILE 경로만 보여야 함)
docker compose config | grep -i password

#Step 8. 수평 확장 체험 — --scale

# app 서비스를 3개로 확장
docker compose up -d --scale app=3

# Nginx 가 늘어난 주소를 다시 조회하게 한다
docker compose restart nginx

# 3개의 app 컨테이너 확인
docker compose ps

# Nginx가 요청을 분산하는지 확인
for i in {1..12}; do curl -s -o /dev/null http://localhost/; done

# 어느 컨테이너가 처리했는지는 Nginx 로그의 upstream 주소로 확인한다
docker compose logs nginx | tail -n 12

# 다시 1개로 줄이기
docker compose up -d --scale app=1

Container visit-counter-compose-app-2  Removing
Container visit-counter-compose-app-3  Removing

docker compose up -d --scale app=3 --force-recreate nginx

log_format upstreamlog '$remote_addr -> $upstream_addr "$request" $status';
access_log /var/log/nginx/access.log upstreamlog;

#Step 9. 정리

# 컨테이너 중지 및 삭제 (볼륨 유지 — 데이터 보존)
docker compose down

# 볼륨까지 삭제 (데이터 초기화)
docker compose down -v

# 빌드 이미지까지 전부 삭제
docker compose down -v --rmi all