Spring Boot JAR 배포 시 application.yml 설정 적용 우선순위

Spring Boot 프로젝트를 JAR 파일로 배포할 때 application.yml 설정이 어떻게 적용되는지 헷갈릴 수 있다.

이번에 개발망 JAR를 실행시키려 했는데 실행이 되지 않았고 JAR 내부에 application.yml이 포함되어 있는 경우, 또는 외부 설정 파일을 사용할 경우 Spring Boot는 특정 우선순위에 따라 설정을 로드한다는 걸 몰랐었다. 이번 글에서는 Spring Boot의 설정 파일 적용 원리와 우선순위를 정리해보았다.

 

---

1. Spring Boot에서 설정 파일 적용 원리

Spring Boot는 application.yml 또는 application.properties 파일을 이용해 애플리케이션 설정을 관리한다. JAR 배포 시, Spring Boot는 설정 파일을 다음과 같은 우선순위에 따라 로드한다.

📌 Spring Boot 설정 파일 우선순위 (높은 순서부터 적용됨)

1. 실행 시 --spring.config.location 옵션으로 지정한 설정 파일
2. 환경 변수 SPRING_CONFIG_LOCATION에 지정된 설정 파일
3. JAR 파일과 같은 디렉터리(./application.yml 또는 ./config/application.yml)
4. JAR 내부 BOOT-INF/classes/application.yml (Spring Boot 프로젝트의 src/main/resources/application.yml)

즉, 외부에 설정 파일이 존재하면 내부 설정보다 우선 적용되며, 외부 설정이 없을 경우 JAR 내부 설정이 기본값으로 사용된다.

 

2. JAR 내부 설정만 있을 경우 (application.yml 포함됨)

JAR 내부에 application.yml이 포함된 경우, 별다른 설정 없이도 Spring Boot는 내부 설정을 자동으로 인식한다.

✅ 실행 방법

java -jar myapp.jar

🔹 이 경우, JAR 내부 BOOT-INF/classes/application.yml이 적용된다.

📌 JAR 내부 설정 포함 여부 확인

JAR 내부에 application.yml이 정상적으로 포함되었는지 확인하려면 아래 명령어를 실행하면 된다.

jar tf myapp.jar | grep application.yml

출력 예시:

BOOT-INF/classes/application.yml

이처럼 BOOT-INF/classes/application.yml이 보이면 내부 설정이 정상적으로 포함된 것이다.

 

3. 외부 application.yml 설정을 적용하는 방법

외부 설정을 적용하고 싶다면, 다음과 같은 방법을 사용할 수 있다.

✅ 방법 1: 실행 시 --spring.config.location 옵션 사용

실행할 때 명시적으로 외부 설정 파일을 지정하면, JAR 내부 설정보다 우선 적용된다.

java -jar myapp.jar --spring.config.location=/path/to/application.yml

또는 설정 파일이 포함된 디렉터리를 지정할 수도 있다.

java -jar myapp.jar --spring.config.location=/path/to/config/

✅ 방법 2: 환경 변수 SPRING_CONFIG_LOCATION 사용

환경 변수로 설정 파일 경로를 지정할 수도 있다.

export SPRING_CONFIG_LOCATION=/path/to/application.yml
java -jar myapp.jar

이렇게 하면 JAR을 실행할 때마다 특정 설정 파일을 강제로 로드할 수 있다.

✅ 방법 3: JAR과 같은 디렉터리 또는 config/ 디렉터리에 application.yml 배치

JAR 파일과 같은 디렉터리 또는 config/ 디렉터리에 application.yml을 두면, Spring Boot는 이를 자동으로 인식하여 내부 설정보다 우선 적용한다.

디렉터리 구조 예시:

/app/
 ├── myapp.jar
 ├── application.yml  # JAR과 같은 경로에 두면 자동 인식됨
 ├── config/
 │   ├── application.yml  # 또는 config 디렉터리에 두어도 인식됨

실행:

java -jar myapp.jar

이렇게 하면 JAR 내부 설정이 아닌 외부 application.yml 설정이 적용된다.

4. application.yml 변경 시 적용 방법

JAR이 실행된 상태에서 application.yml을 변경해도 즉시 반영되지 않는다.

📌 변경 사항을 반영하려면 서버를 재시작해야 한다.

systemctl restart myapp  # systemd 사용 시

또는 수동으로 실행 중인 프로세스를 종료하고 다시 실행:

kill -9 $(ps -ef | grep myapp.jar | grep -v grep | awk '{print $2}')
nohup java -jar myapp.jar &

 

5. spring.profiles.active를 활용한 설정 관리 (추천)

Spring Boot에서는 여러 개의 설정 파일을 spring.profiles.active를 이용해 쉽게 관리할 수 있다.

📌 application.yml에서 기본 프로파일 지정

spring:
  profiles:
    active: dev  # 기본 프로파일을 'dev'로 설정

📌 각 환경별 설정 파일 분리

📌 application-dev.yml

server:
  port: 8081

📌 application-prod.yml

server:
  port: 8082

실행 시 프로파일을 지정하면 해당 설정이 적용된다.

java -jar myapp.jar --spring.profiles.active=prod

이렇게 하면 application-prod.yml이 적용되며, application.yml 기본 설정보다 우선 적용된다.

 

 

🔹 정리

📌 적용 방법우선순위

--spring.config.location=/path/to/application.yml	✅ 최우선
환경 변수 SPRING_CONFIG_LOCATION	✅ 높은 우선순위
JAR과 같은 디렉터리 /application.yml 또는 config/application.yml	✅ 내부 설정보다 우선 적용됨
JAR 내부 /BOOT-INF/classes/application.yml	🔹 최후의 기본 설정

✅ 외부 설정을 적용하려면 --spring.config.location을 지정하거나, JAR과 같은 디렉터리 또는 config/ 디렉터리에 application.yml을 두는 것이 가장 간편한 방법이다.

✅ 여러 개의 설정 파일이 필요하다면 spring.profiles.active를 활용하는 것이 좋다.

 

 

---

Spring Boot JAR 배포 시 설정 파일이 적용되는 원리를 이해하고, 필요에 맞게 적절한 설정 방식을 선택하자!