Docker Compose에서 Spring Boot와 React를 함께 사용하는 방법 (백엔드·프론트 통합 개발 환경 구축)

1. 개요

백엔드(Spring Boot)와 프론트엔드(React)를 동시에 개발할 때 가장 번거로운 부분은 개발 환경을 일관되게 유지하는 것입니다.

특히 다음과 같은 문제가 자주 발생합니다.

• 개발자마다 환경이 다름
• Node / Java 버전 차이
• API 연결 문제
• CORS 문제
• 실행 순서 문제

이 문제를 해결하는 대표적인 방법이 Docker Compose 기반 통합 개발 환경입니다.

Docker Compose를 이용하면 다음과 같은 구조를 만들 수 있습니다.

React (Frontend)
↓
Spring Boot (Backend)
↓
Database (PostgreSQL / MySQL)

 

이 모든 서비스를 한 번의 명령으로 실행할 수 있습니다.

docker compose up

 

---

2. 전체 아키텍처

Docker Compose 기반 구조는 보통 다음과 같습니다.

project
├ backend (Spring Boot)
├ frontend (React)
└ docker-compose.yml

 

실행 구조

Browser
↓
React (Container)
↓
Spring Boot (Container)
↓
Database (Container)

 

네트워크는 Docker 내부 네트워크로 자동 연결됩니다.

---

3. Spring Boot Dockerfile 구성

Spring Boot 프로젝트에 Dockerfile을 작성합니다.

backend/Dockerfile

 

 

FROM eclipse-temurin:17-jdk

WORKDIR /app

COPY build/libs/app.jar app.jar

ENTRYPOINT ["java","-jar","app.jar"]

 

Gradle 빌드

./gradlew build

 

 

---

4. React Dockerfile 구성

React는 Node 기반으로 빌드합니다.

frontend/Dockerfile

 

 

FROM node:20

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

CMD ["npm","run","dev"]

 

Vite 또는 React 개발 서버가 실행됩니다.

---

5. docker-compose.yml 구성

Docker Compose에서 두 서비스를 함께 실행합니다.

 

version: "3.8"

services:

backend:
build: ./backend
ports:
- "8080:8080"
networks:
- app-network

frontend:
build: ./frontend
ports:
- "3000:3000"
depends_on:
- backend
networks:
- app-network

networks:
app-network:

 

실행

docker compose up

 

---

6. React에서 Spring Boot API 호출

Docker 환경에서는 localhost를 사용하면 안 됩니다.

React에서 API 호출은 다음과 같이 합니다.

http://backend:8080/api

 

왜냐하면 Docker Compose 내부에서는

서비스 이름 = 호스트 이름

 

이기 때문입니다.

예시

 

fetch("http://backend:8080/api/users")

 

---

7. CORS 설정

Spring Boot에서 React 요청을 허용해야 합니다.

 

@Configuration
public class CorsConfig {

@Bean
public WebMvcConfigurer corsConfigurer() {
return new WebMvcConfigurer() {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
.allowedOrigins("*")
.allowedMethods("*");
}
};
}
}

 

---

8. 개발 환경 최적화

개발 시에는 Hot Reload가 중요합니다.

React

npm run dev

 

Spring Boot

spring-boot-devtools

 

또는 Docker volume 사용

 

volumes:
- ./backend:/app

 

---

9. 실행 결과

실행 후 접속

React
http://localhost:3000

Spring Boot
http://localhost:8080

 

React → Spring Boot API 호출이 정상 동작합니다.

---

10. Docker Compose 방식의 장점

1️⃣ 환경 통일

모든 개발자 동일 환경

 

---

2️⃣ 실행 단순화

docker compose up

 

한 번으로 전체 시스템 실행

---

3️⃣ 서비스 분리

Frontend
Backend
DB

 

독립적으로 관리 가능

---

4️⃣ CI/CD 연계

Docker Compose 구조는 그대로

Kubernetes
Cloud

 

로 확장 가능합니다.

---

11. 결론

Docker Compose를 활용하면 Spring Boot와 React 개발 환경을 하나의 통합 시스템으로 구성할 수 있습니다.

핵심 포인트는 다음과 같습니다.

• 서비스별 Dockerfile 구성
• docker-compose.yml로 서비스 연결
• Docker 네트워크 기반 API 호출
• CORS 설정

이 구조는 로컬 개발 환경뿐 아니라 CI/CD 및 클라우드 배포까지 확장 가능한 아키텍처입니다.