Docker 환경에서 AWS S3 리전 에러 및 API 404 발생 시 문제 해결 가이드

문제 상황 (Problem Description)

Spring Boot 애플리케이션 개발 중, 로컬 환경(java -jar 또는 IDE 실행)에서는 모든 기능이 정상 동작했지만, docker-compose up으로 컨테이너 환경에서 실행했을 때만 S3 파일 업로드 및 다른 API 호출이 실패하는 문제가 발생했습니다.

• 주요 증상 (핵심 단서): AWS S3 파일 업로드 시, 버킷이 분명히 ap-northeast-2(서울) 리전에 있음에도 불구하고 The bucket is in this region: us-east-1 라는 301 PermanentRedirect 에러가 발생했습니다.
• 연관 증상: @PostMapping으로 정의된 다른 API들은 404 Not Found 에러를 반환했습니다.
• 공통점: 모든 기능은 로컬 환경에서는 완벽하게 동작했습니다.

 

핵심 원인 (Root Cause)

문제의 핵심 원인은 로컬 실행 환경과 Docker 컨테이너 실행 환경 간의 설정 불일치였습니다.

이번 사례의 주요 원인은 docker-compose.yml에 .env 파일을 환경 변수로 주입하는 env_file 설정이 누락되어, Docker 컨테이너가 .env 파일의 내용을 전혀 읽지 못한 것이었습니다.

이로 인해 다음과 같은 연쇄적인 문제가 발생했습니다.

1. S3 리전 및 버킷 이름 누락: 컨테이너 내부의 AWS SDK는 환경 변수(AWS_REGION, AWS_S3_BUCKET_NAME 등)를 읽을 수 없었습니다. AWS SDK는 리전 정보가 없을 경우 기본값(default)으로 us-east-1 리전을 사용하게 되므로, ap-northeast-2에 있는 버킷에 접근 시도 시 PermanentRedirect 에러가 발생했습니다.
2. context-path 누락: 동일한 이유로 .env 파일에 정의된 SERVER_SERVLET_CONTEXT_PATH 환경 변수 또한 누락되었습니다. 그 결과, Spring Boot 애플리케이션이 context-path 없이 실행되어 모든 API 엔드포인트의 주소가 달라졌고, 이는 404 Not Found 에러로 이어졌습니다.

 

최종 해결책 (Final Solution) 

docker-compose.yml 파일에 env_file 속성을 추가하여, 컨테이너 실행 시 .env 파일의 변수들을 환경 변수로 주입하도록 수정했습니다.

수정 전

services:
  uritrip-java-server:
    build: .
    ports:
      - "8080:8080"
    # env_file 설정이 누락되어 있었음

수정 후

services:
  uritrip-java-server:
    build: .
    ports:
      - "8090:8090"
    env_file:
      - .env  # <-- 이 한 줄을 추가하여 문제 해결

수정 후 docker-compose up -d --build 명령어로 컨테이너를 재시작하자 모든 S3 및 API 기능이 정상적으로 동작했습니다.