정보

[Spring Boot] .jar 실행 시 알아두면 좋은 필수 옵션 총정리 (프로파일, 포트, 외부 설정파일까지)

mindlab091904 2025. 5. 9. 16:32
반응형

 

Spring Boot는 자바 개발자에게 있어 현대적인 웹 애플리케이션 구축을 위한 강력한 프레임워크입니다. 대부분의 경우, 개발을 완료한 후 .jar 파일 형태로 패키징하여 배포하고, 이 .jar 파일을 서버에서 직접 실행하게 됩니다.

하지만 단순히 java -jar만으로 실행하는 것보다, 상황에 따라 다양한 옵션을 설정하여 좀 더 유연하게 애플리케이션을 운영할 수 있습니다. 오늘은 Spring Boot .jar 파일 실행 시 유용하게 사용할 수 있는 다양한 실행 옵션들을 정리하여 소개드립니다.

✅ 기본 실행 명령어: java -jar

가장 기본적인 실행 방식은 다음과 같습니다.

java -jar myapp.jar

위 명령어만으로도 애플리케이션은 정상적으로 실행되며, 내부에 포함된 application.properties 또는 application.yml 설정에 따라 기본 포트(보통 8080번)로 동작하게 됩니다.

하지만 실무에서는 환경마다 설정이 다르기 때문에 이 기본 실행 방식만으로는 부족할 수 있습니다. 이를 보완하기 위해 다음과 같은 옵션들이 존재합니다.

✅ 서버 포트 변경: --server.port

기본적으로 Spring Boot 애플리케이션은 8080 포트에서 실행됩니다. 하지만 이미 사용 중인 포트일 수도 있고, 여러 애플리케이션을 동시에 띄워야 할 경우에는 포트를 변경해주어야 합니다.

java -jar myapp.jar --server.port=8081

이렇게 실행하면, myapp.jar 애플리케이션이 8081 포트에서 동작하게 됩니다. 포트를 자주 바꿔야 하는 테스트 환경 등에서 매우 유용하게 사용됩니다.

✅ 프로파일 설정: --spring.profiles.active vs -Dspring.profiles.active

Spring Boot는 application.properties나 application.yml 외에도 프로파일을 통한 설정 분리가 가능합니다. 예를 들어 개발 환경, 운영 환경, 스테이징 환경에 따라 설정을 다르게 가져가고 싶을 때 유용합니다.

방법 1. 실행 옵션에 직접 설정

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

이 방식은 Spring Boot가 내부적으로 프로파일을 인식하고 application-prod.properties 혹은 application-prod.yml 파일을 읽어 적용합니다.

방법 2. JVM 옵션으로 설정 (-D)

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

이 방식은 JVM 시스템 프로퍼티로 전달되며, 애플리케이션 내부에서 다음과 같이 접근할 수 있습니다.

System.getProperty("spring.profiles.active");

✅ 주의사항
--spring.profiles.active는 스프링 프레임워크 내부에서 사용되는 설정이며,
-Dspring.profiles.active는 JVM 레벨에서 설정되는 시스템 프로퍼티입니다.
기능은 유사하지만 동작 계층이 다르므로 상황에 맞게 선택해야 합니다.

✅ 외부 설정파일 적용: --spring.config.location

운영 환경에서는 .jar 내부에 설정 파일을 넣지 않고, 외부에 application.properties 또는 application.yml을 별도로 두고 이를 불러오는 방식이 선호됩니다. 이유는 설정 변경 시 .jar를 다시 빌드하지 않아도 되기 때문입니다.

java -jar myapp.jar --spring.config.location=file:/home/configs/application.properties

이렇게 하면 .jar 내부가 아닌, /home/configs 경로에 있는 설정파일을 읽어옵니다.

✅ 여러 설정파일 로드

복수의 설정파일을 동시에 불러올 수도 있습니다. 쉼표(,)로 구분하면 됩니다.

java -jar myapp.jar --spring.config.location=file:/home/configs/base.properties,file:/home/configs/prod.properties

이 경우, 앞의 설정값이 뒤의 설정으로 덮어쓰기 되므로 순서에 주의해야 합니다. 예를 들어, base.properties에 공통 설정이, prod.properties에 운영 환경에 맞춘 오버라이딩 설정이 들어있는 식입니다.

✅ 환경변수와 명령어 인자의 우선순위

Spring Boot는 설정을 가져오는 데 있어 우선순위를 명확히 따릅니다. 이를 이해하면 설정 충돌을 방지할 수 있습니다.

  1. command line arguments (ex. --server.port=8081)
  2. SPRING_APPLICATION_JSON (환경변수에 JSON으로 설정값 주입)
  3. OS 환경 변수
  4. Java 시스템 프로퍼티 (ex. -Dspring.profiles.active=prod)
  5. application.properties 또는 application.yml
  6. @PropertySource 어노테이션
  7. 기본값

✅ 실무에서 자주 쓰는 실행 예시 모음

아래는 실제 운영 및 개발 환경에서 자주 사용되는 실행 명령어 예시입니다.

📌 개발용 테스트 실행

java -jar myapp.jar --spring.profiles.active=dev --server.port=9000

📌 운영환경 실행 (외부 설정파일 포함)

java -jar myapp.jar --spring.profiles.active=prod \
  --spring.config.location=file:/etc/myapp/configs/ \
  --server.port=8080

📌 JVM 시스템 프로퍼티 사용

java -Dspring.profiles.active=staging \
  -Dserver.port=8070 \
  -jar myapp.jar

✅ TIP: 배포 자동화를 위한 스크립트 작성

서버에서 매번 긴 명령어를 입력하는 건 비효율적입니다. 아래와 같이 .sh 파일로 실행 스크립트를 만들어두면 관리가 편해집니다.

start.sh

#!/bin/bash
JAR_NAME="myapp.jar"
PROFILE="prod"
PORT="8080"
CONFIG_PATH="/home/myapp/configs/"

java -jar $JAR_NAME \
  --spring.profiles.active=$PROFILE \
  --spring.config.location=file:$CONFIG_PATH \
  --server.port=$PORT

✅ 마무리하며

Spring Boot 애플리케이션을 .jar 파일로 배포할 때, 단순히 java -jar만 사용하는 것은 매우 기본적인 접근입니다. 하지만 다양한 실행 옵션을 적극적으로 활용하면, 환경에 따라 더 유연하고 안정적인 서비스 운영이 가능합니다.

특히 프로파일을 통한 설정 분리, 외부 설정파일 사용, 포트 조정 등은 실무에서 필수로 익혀야 할 부분입니다. 이 포스팅이 여러분의 Spring Boot 애플리케이션 운영에 실질적인 도움이 되었길 바랍니다.

📎 관련 태그

#SpringBoot #스프링부트 #jar실행옵션 #SpringProfiles #서버포트변경 #외부설정파일 #java실행 #JVM옵션 #애플리케이션배포 #Spring실무

 

반응형