WildFly WAR 배포가 진행되지 않을 때: dodeploy와 deployed 파일 구분 및 점검 방법

WildFly WAR 배포가 진행되지 않을 때: dodeploy와 deployed 파일 구분 및 점검 방법

WildFly의 deployments 디렉터리에 WAR 파일을 넣었지만 서비스가 올라오지 않는 경우가 있다. 로그에는 WAR 파일명이나 배포 관련 메시지가 보이는데, 이후 완료 또는 실패 메시지가 나타나지 않아 어디부터 확인해야 할지 애매한 상황이다.

이때는 먼저 배포 요청이 접수되지 않은 상태인지, 배포가 시작된 뒤 멈춘 상태인지를 구분해야 한다. 두 상황은 점검 방향과 조치 방법이 다르다.

먼저 파일 확장자를 정확히 구분하자.

사용자가 빈 파일을 만들어 배포를 요청할 때 사용하는 이름은 파일.war.dodeploy다. 파일.war.deployed는 배포 성공 후 WildFly가 생성하는 상태 표시 파일이다. 따라서 .deployed를 직접 만드는 방법을 정상적인 배포 절차로 사용하면 안 된다.

1. 적용 대상과 발생 증상

이 글은 Linux에서 WildFly를 Standalone 모드로 실행하고, 파일 시스템 Deployment Scanner를 이용해 WAR를 배포하는 환경을 기준으로 한다. 관리 콘솔이나 CLI로 배포한 애플리케이션은 마커 파일만으로 상태를 판단하지 않는다.

대표적인 증상은 다음과 같다.

• standalone/deployments에 WAR 파일을 복사했지만 애플리케이션이 실행되지 않는다.
• 로그에 WAR 파일명이 보이지만 배포 완료 메시지가 확인되지 않는다.
• WAR 파일만 남아 있고 배포 결과를 나타내는 마커 파일이 생성되지 않는다.
• 배포 시작 메시지 이후 추가 로그가 출력되지 않는다.

“WAR 파일을 호출했다”는 설명만으로는 실제 배포 단계를 확정할 수 없다. 마지막 로그의 원문, 발생 시각, 마커 파일 상태를 함께 확인해야 한다.

2. dodeploy와 deployed 파일의 차이

Deployment Scanner는 WAR 파일 옆에 있는 마커 파일을 이용해 배포 요청과 처리 상태를 관리한다.

example.war 기준 주요 마커 파일

파일명	역할	점검 관점
example.war.dodeploy	사용자가 생성하는 배포·재배포 요청	Scanner가 요청을 처리하는지 확인한다.
example.war.isdeploying	Scanner가 표시하는 배포 진행 상태	오래 유지되면 배포 로그와 초기화 작업을 확인한다.
example.war.deployed	Scanner가 생성하는 배포 성공 표시	관리 상태와 실제 서비스 응답도 함께 확인한다.
example.war.failed	배포 실패 표시와 원인 정보	파일 내용을 읽고 실패 원인을 조치한다.
example.war.pending	배포 필요성을 감지했지만 아직 요청하지 못한 상태	복사 중인 파일이나 자동 배포를 막는 조건을 확인한다.
example.war.skipdeploy	해당 콘텐츠의 자동 배포 억제	작업자가 의도적으로 생성했는지 확인한다.
example.war.undeployed	배포 해제 상태 표시	해제 이력과 이후 배포 요청 여부를 확인한다.

이 구분은 WildFly 공식 관리 가이드의 Application deployment 항목을 기준으로 한다.

마커 파일을 한꺼번에 삭제하지 않는다. Scanner가 관리하는 .deployed 파일을 삭제하면 배포 해제가 발생할 수 있다. 장애 원인을 확인하기 전에 상태 파일부터 지우면 서비스 상태가 바뀌거나 분석 단서를 잃을 수 있다.

3. 가장 먼저 배포 경로와 현재 상태 확인하기

3.1 실제 실행 중인 WildFly 확인

아래 경로는 예시다. 서버에 설치된 WildFly 경로로 변경하고, 가능하면 WildFly 실행 계정으로 점검한다.

WILDFLY_HOME=/opt/wildfly
WILDFLY_BASE="$WILDFLY_HOME/standalone"

ps -ef | grep '[o]rg.jboss.as.standalone'

ls -ld "$WILDFLY_BASE/deployments"
ls -lh "$WILDFLY_BASE/deployments"/example.war*

프로세스 실행 옵션에 -Djboss.server.base.dir가 있으면 기본 standalone 경로와 다른 인스턴스 디렉터리를 사용하고 있을 수 있다. Scanner의 path 설정도 별도로 변경할 수 있으므로 실제 감시 경로를 확인해야 한다.

3.2 실패 파일과 로그 확인

if [ -f "$WILDFLY_BASE/deployments/example.war.failed" ]; then
    cat "$WILDFLY_BASE/deployments/example.war.failed"
fi

tail -n 200 "$WILDFLY_BASE/log/server.log"

grep -nE 'example\.war|WFLYSRV|WFLYCTL|ERROR|Exception|Caused by' \
    "$WILDFLY_BASE/log/server.log" | tail -n 100

필터 검색은 위치를 찾기 위한 용도다. 예외의 앞뒤 문맥과 여러 줄로 출력되는 원인 정보는 원본 로그에서 확인한다. 로그가 회전되었다면 해당 시각의 이전 로그도 확인한다.

4. WAR만 있고 배포가 시작되지 않을 때

WAR 파일 복사가 완료되었고, 진행 중인 배포도 없으며, Scanner가 정상 동작하는 상황이라면 .dodeploy 파일로 배포를 요청할 수 있다.

4.1 WAR 파일 확인

ls -lh "$WILDFLY_BASE/deployments/example.war"
file "$WILDFLY_BASE/deployments/example.war"

# unzip이 설치되어 있다면 압축 무결성 확인
unzip -t "$WILDFLY_BASE/deployments/example.war"

파일 전송이 끝났는지 확인한 뒤 진행한다. 압축 검사가 성공해도 Java 버전, API 호환성, 라이브러리 및 설정 문제까지 검증되는 것은 아니다.

4.2 빈 dodeploy 파일 생성

기존 배포가 있다면 아래 요청은 재배포로 처리될 수 있으므로 서비스 영향을 확인한다.

touch "$WILDFLY_BASE/deployments/example.war.dodeploy"

파일 안에 내용을 작성할 필요는 없다. WAR 파일명 전체 뒤에 .dodeploy를 붙이는 것이 핵심이다.

4.3 배포 처리 결과 확인

tail -f "$WILDFLY_BASE/log/server.log"

다른 터미널에서 마커 파일 변화를 확인한다.

ls -lh "$WILDFLY_BASE/deployments"/example.war*

성공하면 Scanner가 .deployed를 생성한다. 실패하면 .failed 내용과 같은 시각의 서버 로그를 확인한다. .dodeploy가 계속 남는다면 감시 경로, Scanner 동작 여부, 파일 권한 등을 점검한다.

5. dodeploy를 만들어도 반응이 없을 때

5.1 Deployment Scanner 설정 조회

관리 포트가 기본값인 로컬 환경의 접속 예시다. 관리 주소·포트·인증 방식은 실제 환경에 맞춘다.

"$WILDFLY_HOME/bin/jboss-cli.sh" --connect

접속 후 다음 명령을 실행한다.

/subsystem=deployment-scanner:read-resource(recursive=true)

실행 중인 Scanner에서 확인할 설정

설정	확인할 내용
scan-enabled	스캔이 활성화되어 있는지 확인한다.
scan-interval	주기적인 스캔 간격이다. 1 미만이면 시작 시에만 스캔한다.
path, relative-to	WAR를 넣은 위치가 실제 감시 경로인지 확인한다.
auto-deploy-zipped	압축 WAR를 마커 없이 자동 배포할지 결정한다. false라면 명시적인 배포 요청이 필요하다.
auto-deploy-exploded	압축을 푼 디렉터리 형태의 자동 배포 설정이다. 압축 WAR와 구분한다.

WAR만으로 배포되지 않는다고 해서 자동 배포 옵션부터 바꿀 필요는 없다. 수동 배포 정책으로 운영하는 환경일 수 있으므로 현재 운영 방식을 먼저 확인한다.

5.2 권한과 다른 대기 파일 확인

ls -ld "$WILDFLY_BASE" "$WILDFLY_BASE/deployments"
ls -l "$WILDFLY_BASE/deployments"/example.war*

find "$WILDFLY_BASE/deployments" -maxdepth 1 -type f \
    \( -name '*.pending' -o -name '*.skipdeploy' \) -print

WildFly 실행 계정은 WAR를 읽고 디렉터리를 탐색할 수 있어야 하며, 감시 디렉터리에 마커 파일을 생성·삭제할 권한도 필요하다. 권한 문제가 확인되면 실행 계정과 운영 정책에 맞게 수정한다.

.pending은 다른 배포 콘텐츠의 처리에도 영향을 줄 수 있다. 대상 WAR뿐 아니라 같은 감시 디렉터리에 복사 중인 다른 파일이 있는지도 확인한다.

6. 배포 시작 로그 이후 멈춘 경우

로그에 단순히 파일명이 등장하는 것과 실제로 배포 시작 메시지가 출력되는 것은 다르다. 예를 들어 Starting deployment of 메시지 이후 진행이 멈췄다면 애플리케이션 초기화 단계에서 대기하고 있을 가능성도 살펴봐야 한다.

이 경우 .dodeploy를 반복 생성하기보다 현재 배포 작업과 JVM 상태를 확인한다.

• 데이터소스 연결, DB 접속 및 커넥션 풀 초기화 대기
• 외부 API, DNS, 인증 서버 등 외부 시스템 응답 대기
• 애플리케이션 초기화 코드의 장시간 실행 또는 잠금 대기
• 라이브러리 충돌, 클래스 로딩 및 Java·API 호환성 문제
• 메모리 부족, 디스크 공간 부족 또는 저장장치 지연
• 배포·관리 작업 시간 초과

위 항목은 가능한 점검 대상이며, 현재 증상만으로 특정 원인을 확정할 수는 없다.

6.1 배포 관리 상태 확인

CLI에서 대상 배포의 관리 정보를 조회한다.

/deployment=example.war:read-resource(include-runtime=true)

조회 결과의 enabled, 제공되는 런타임 status, 실패 응답을 확인한다. 리소스가 없다는 응답은 배포가 아직 등록되지 않았거나 이름이 다를 때도 발생할 수 있다. 진행 중인 관리 작업이 있으면 조회 응답도 지연될 수 있다.

6.2 필요하면 JVM 스레드 상태 확인

배포 시작 이후 응답이 없고 원인이 로그에 드러나지 않는다면 JDK의 jcmd를 사용할 수 있다. WildFly와 같은 실행 계정으로 실제 Java PID를 확인한 뒤 실행한다.

jcmd -l

# 12345는 실제 WildFly Java PID로 변경
jcmd 12345 Thread.print

스레드 덤프에서 네트워크 연결 대기, 잠금 경합, 초기화 코드 실행 위치를 확인한다. 도구 사용 가능 여부와 프로세스 연결 권한은 JDK 및 실행 환경에 따라 다르다.

7. 배포 완료와 서비스 정상 여부 확인

확인은 마커 파일 → 서버 로그·관리 상태 → 실제 HTTP 응답 순서로 진행한다. 파일이 생성되었다는 사실만으로 업무 기능까지 정상이라고 판단하지 않는다.

ls -l "$WILDFLY_BASE/deployments/example.war.deployed"

grep -n 'example.war' "$WILDFLY_BASE/log/server.log" | tail -n 30

# 실제 애플리케이션 포트와 컨텍스트 경로로 변경
curl -i --connect-timeout 5 --max-time 15 \
    http://127.0.0.1:8080/example/

컨텍스트 경로는 설정에 따라 WAR 파일명과 다를 수 있다. 인증이 필요한 서비스라면 302 또는 401 응답이 예상될 수 있으므로 정상 응답 기준에 맞춰 확인한다. 404가 발생하면 배포 상태와 함께 컨텍스트 경로 및 요청 URL도 점검한다.

8. 현장 조치 내용 정리 예시

실제로 .dodeploy 생성 후 배포가 완료된 경우에는 다음과 같이 기록할 수 있다.

증상: WildFly 감시 디렉터리에 WAR 파일을 배치했으나 배포 완료 로그와 서비스 기동이 확인되지 않았다.

확인: 실제 배포 경로와 Scanner 설정, WAR 전송 완료 여부 및 마커 파일 상태를 확인했다.

조치: 해당 WAR에 대한 .dodeploy 파일을 생성하여 Deployment Scanner에 배포를 명시적으로 요청했다.

결과: 서버가 생성한 .deployed 파일, 배포 완료 로그 및 서비스 응답으로 정상 배포를 확인했다.

원인 판단: 수동 요청 이후 정상 배포된 사실만으로 최초 미배포 원인까지 확정하지 않는다. 자동 배포 설정, 스캔 상태 및 당시 로그를 근거로 원인을 구분한다.

기억해야 할 명령은 touch example.war.dodeploy다. 다만 이미 배포가 시작된 상태라면 마커 파일 생성보다 멈춘 초기화 단계와 로그를 먼저 분석해야 한다.

참고 문서

• WildFly 공식 관리 가이드 — 배포 마커와 배포 절차
• WildFly Deployment Scanner 관리 모델 — 설정 속성 설명

참고 문서의 버전과 실제 운영 버전이 다르면 속성 지원 여부와 기본값을 실행 중인 서버에서 확인한다.