#Liberty

[WebSphere Liberty] 설정 유연화의 핵심: 변수(Variable) 활용법 및 우선순위 완벽 정리

WebSphere Liberty의 설정 파일(server.xml)에서 포트 번호, DB 접속 정보 등을 하드코딩하지 않고 변수(Variable)로 관리하는 방법을 정리합니다. bootstrap.properties와 server.xml, 환경 변수 간의 우선순위 규칙과 JDBC URL 설정 시 발생하는 슬래시(/) 정규화 문제를 해결하는 팁을 다룹니다.

0. 변수를 왜 사용해야 하나요?

서버 설정을 변수화하면 하나의 server.xml 파일을 여러 서버 인스턴스나 환경(Dev/Test/Prod)에서 공유할 수 있습니다. 변경되는 값(포트, IP 등)만 별도로 분리하여 관리 효율성을 높일 수 있습니다.

1. 변수 정의 위치 및 우선순위 (Precedence)

Liberty에서 변수를 정의할 수 있는 곳은 크게 세 군데입니다. 만약 같은 이름의 변수가 여러 곳에 정의되어 있다면, 아래 순서대로 덮어씌워집니다. (아래쪽이 우선순위 높음)

  1. 프로세스 환경 변수 (OS Environment Variables): 가장 낮은 우선순위
  2. bootstrap.properties: 환경 변수를 덮어씀
  3. server.xml (또는 include 된 xml): 가장 높은 우선순위 (최종 승자)
Best Practice:
서버별로 달라지는 고유 설정(예: HTTP 포트)은 bootstrap.properties에 정의하고, 여러 서버가 공유하는 공통 설정(예: DB 설정)은 included xml 파일에 정의하는 것이 좋습니다.

2. 변수 사용 방법 (Usage Guide)

Case A: bootstrap.properties 활용

서버 인스턴스 생성 시 자동으로 만들어지는 파일로, key=value 형태로 간단하게 정의합니다.

# bootstrap.properties
# 포트 번호 정의
http.port=8080
https.port=9443

Case B: server.xml 활용

<variable> 태그를 사용하여 정의하거나, 정의된 변수를 ${...} 문법으로 사용합니다.

<!-- 변수 정의 (Global) -->
<variable name="http.port" value="8080" />

<!-- 변수 사용 -->
<httpEndpoint id="defaultHttpEndpoint"
              httpPort="${http.port}"
              httpsPort="${https.port}" />

Case C: 환경 변수(Environment Variable) 활용

OS 환경 변수를 가져올 때는 env. 접두사를 사용합니다.

<!-- OS의 LIBRARY_DIR 환경 변수 사용 -->
<fileset dir="${env.LIBRARY_DIR}" includes="*.jar"/>

3. 고급 활용 팁 (Advanced Tips)

1) JDBC URL 슬래시(/) 정규화 문제 해결

Liberty 설정 파서(Parser)는 변수 값에 포함된 연속된 슬래시(//)를 단일 슬래시(/)로 정규화하는 특성이 있습니다. 이 때문에 JDBC URL 등이 깨질 수 있습니다.

해결책: 값을 두 부분으로 나누어 정의하거나, 이중 슬래시로 시작하게 합니다.

# [Bad] 이렇게 하면 jdbc:db2:/host.com 으로 변환되어 에러 발생
# DB_URL="jdbc:db2://host.com"

# [Good] 두 부분으로 나누어 결합
URL_PART_1="jdbc:db2:"
URL_PART_2="//host.com"
<dataSource ...>
    <properties.db2.jcc url="${URL_PART_1}${URL_PART_2}" />
</dataSource>

2) 리스트(List) 변수 처리

콤마(,)로 구분된 값을 단순 문자열이 아닌 리스트로 인식시키려면 ${list(...)} 함수를 사용합니다.

<variable name="ports" value="80,9080"/>

<!-- 문자열 "80, 9080"으로 인식 -->
<myConfig value="${ports}" /> 

<!-- 리스트 ["80", "9080"]으로 인식 -->
<myConfig value="${list(ports)}" />

3) 산술 연산 (Arithmetic)

포트 오프셋 등을 설정할 때 간단한 사칙연산(+, -, *, /)이 가능합니다.

<!-- 기본 포트(8080)에 1을 더해 8081로 설정 -->
<httpEndpoint id="secondaryEndpoint" httpPort="${http.port+1}" />

4. 변수 명명 규칙 (Naming Convention)

변수 이름은 반드시 알파벳(문자)으로 시작해야 하며, 아래 문자들만 포함할 수 있습니다.

  • 알파벳 문자 (Alphabetic characters)
  • 숫자 (Numeric characters)
  • 언더스코어 (_)
  • 점 (.)

Next Step:
이제 server.xml에서 하드코딩된 값을 제거하고 bootstrap.properties로 옮겨보십시오. 이를 통해 Docker 이미지 빌드나 여러 환경 배포 시 설정 관리가 훨씬 수월해질 것입니다.