Spring Boot + Redis + Docker 연결 문제 트러블 슈팅

 

오늘은 Spring Boot 애플리케이션에서 Redis를 사용할 때, 로컬에서 실행할 때와 Docker Compose 환경에서 실행할 때 설정 방식이 다르기 때문에 자주 겪는 트러블에 대해 정리했다.

 

---

✅  문제 상황

로컬 환경에서 Redis 연결은 잘 되는데, Docker 컨테이너로 배포하면 아래와 같은 에러가 발생했다:

spring.data.redis.host=localhost
spring.data.redis.port=6379

 

즉, 도커 컨테이너 환경에서도 Redis를 localhost로 접근하는 문제가 발생한 것이다.

---

✅  원인 추론

로컬 머신과 Docker 컨테이너에서의 Redis 접근 방법이 다르기 때문이다.

• 로컬 환경
  • Redis는 내 컴퓨터에 직접 설치되어 실행되므로, localhost:6379로 접근한다.
• Docker 환경
  • Redis는 Docker 컨테이너로 실행되고, Spring Boot 앱과 같은 Docker 네트워크 내에서 서로 다른 컨테이너 간 통신이 이루어져야 한다.
  • 따라서 Docker Compose에서 정의된 컨테이너의 이름을 사용해야 한다. (예: redis)

즉, Docker 컨테이너 내의 앱이 Redis를 localhost로 접근하면, 본인의 컨테이너 내에서 Redis를 찾으므로 실패하게 된다.

 

---

✅ 해결 방법

아래와 같이 환경별로 설정값을 분리하여 적용한다.

1️⃣ 로컬 실행 시 (application.properties)

spring.data.redis.host=localhost
spring.data.redis.port=6379

2️⃣ Docker 실행 시 (application.properties)

Docker 환경에서는 docker-compose.yml에 정의된 Redis 컨테이너의 이름을 사용해야 한다.

services:
  redis:
    image: redis:alpine
    container_name: redis
    ports:
      - "6379:6379"
    networks:
      - nest-network

 

그래서 Spring Boot 설정 파일은 이렇게 바꿔준다:

spring.data.redis.host=redis
spring.data.redis.port=6379

 

즉, Redis 컨테이너의 이름(redis)을 사용해 연결해야 한다.

 

 

트러블 슈팅 정리

환경	Redis 호스트 설정
로컬 환경	localhost
Docker 환경	Docker Compose 컨테이너 이름 (redis)

 

💡 알기만 했다면 간단한 내용이지만, 도커를 처음 배포할 때는 개념이 부족해서 놓치기 쉬운 환경별 설정 방법을 명확히 정리했다.
이제 이 내용을 제대로 이해했으니, 앞으로 Redis와 Docker를 사용할 때 비슷한 문제를 더 쉽게 해결할 수 있을 것 같다.