Windows에서는 FineReport Designer를 사용하고, WSL 2의 Ubuntu에는 FineReport Server를 설치하는 방법을 정리했다.
이 글은 로컬 개발·테스트 환경을 기준으로 한다. 실제 운영 환경에서는 별도의 Linux 서버와 외부 데이터베이스 사용을 권장한다.
구성
Windows
├─ FineReport Designer
├─ 웹 브라우저
└─ WSL 2
└─ Ubuntu
└─ FineReport 11 Server
├─ Tomcat 9
├─ Temurin Java 8
└─ FineDB테스트 환경
| 항목 | 환경 |
|---|---|
| 호스트 OS | Windows |
| Linux 환경 | WSL 2 |
| Linux 배포판 | Ubuntu 64-bit |
| FineReport | 11.0 한국어판 |
| 서버 패키지 | tomcat-linux_KO.tar.gz |
| Tomcat | 9.0.105 |
| Java | Temurin JDK 8 |
| 기본 포트 | 8080 |
FineReport는 Linux 서버 배포를 지원한다. 자세한 내용은 FineReport Linux 배포 공식 문서에서 확인할 수 있다.
1. WSL 2 확인
Windows PowerShell에서 확인한다.
wsl --list --verboseUbuntu의 VERSION이 2로 표시되어야 한다.
NAME STATE VERSION
Ubuntu Running 2Ubuntu 터미널에서 OS와 CPU 아키텍처를 확인한다.
cat /etc/os-release
uname -m일반적인 Intel·AMD 기반 PC라면 다음과 같이 표시된다.
x86_64ARM 기반 PC라면 ARM64용 FineReport 패키지가 필요하다.
2. 서버 패키지 확인
이 글에서는 Windows 다운로드 폴더에 다음 파일이 있다고 가정한다.
C:\Users\WINDOWS_USER\Downloads\tomcat-linux_KO.tar.gzWINDOWS_USER는 실제 Windows 사용자 폴더 이름으로 바꾼다.
WSL에서 파일을 확인한다.
ls -lh /mnt/c/Users/WINDOWS_USER/Downloads/tomcat-linux_KO.tar.gz압축을 풀기 전에 FineReport 버전을 확인한다.
tar -tzf /mnt/c/Users/WINDOWS_USER/Downloads/tomcat-linux_KO.tar.gz \
| grep 'fine-core'FineReport 11 패키지라면 다음 파일이 표시된다.
tomcat-linux_KO/webapps/webroot/WEB-INF/lib/fine-core-11.0.jarfine-core-10.0.jar가 표시된다면 FineReport 10 서버 패키지이므로 FineReport 11 Designer와 함께 사용하지 않는 것이 좋다.
3. WSL 내부에 설치
Windows 드라이브인 /mnt/c에서 직접 서버를 실행하지 않고 WSL 내부 Linux 파일시스템에 설치한다.
mkdir -p ~/apps
tar -xzf /mnt/c/Users/WINDOWS_USER/Downloads/tomcat-linux_KO.tar.gz \
-C ~/apps설치 결과를 확인한다.
ls -la ~/apps/tomcat-linux_KO
du -sh ~/apps/tomcat-linux_KO다음 디렉터리가 있으면 정상적으로 해제된 것이다.
bin
conf
jdk
lib
logs
temp
webapps4. 실행 권한 설정
배포 패키지에 따라 Java 실행 파일이나 셸 스크립트의 실행 권한이 빠져 있을 수 있다.
chmod u+x ~/apps/tomcat-linux_KO/bin/*.sh
chmod u+x ~/apps/tomcat-linux_KO/jdk/bin/java
chmod u+x ~/apps/tomcat-linux_KO/jdk/jre/bin/java권한을 확인한다.
ls -l ~/apps/tomcat-linux_KO/bin/startup.sh
ls -l ~/apps/tomcat-linux_KO/jdk/jre/bin/java파일 권한에 x가 포함되어야 한다.
-rwxr-xr-x5. 포트와 Tomcat 설정 검사
FineReport 배포 패키지는 기본적으로 8080 포트를 사용한다.
ss -ltn | grep ':8080 '아무것도 출력되지 않으면 포트를 사용할 수 있다. 다른 프로그램이 출력된다면 해당 프로그램을 종료하거나 다음 파일에서 FineReport 포트를 변경한다.
~/apps/tomcat-linux_KO/conf/server.xmlTomcat 설정을 검사한다.
cd ~/apps/tomcat-linux_KO
JAVA_HOME="$PWD/jdk" \
JRE_HOME="$PWD/jdk/jre" \
./bin/configtest.sh정상이면 Tomcat, Linux, Java 정보와 다음 메시지가 표시된다.
Initializing ProtocolHandler ["http-nio-8080"]6. systemd 확인
FineReport를 백그라운드 서비스로 관리하기 위해 systemd 상태를 확인한다.
systemctl is-system-runningrunning이 나오면 다음 단계로 넘어간다.
systemd가 비활성화되어 있다면 다음 파일을 연다.
sudo nano /etc/wsl.conf다음 내용을 추가한다.
[boot]
systemd=true저장한 뒤 Windows PowerShell에서 WSL을 종료하고 다시 실행한다.
wsl --shutdown7. FineReport 서비스 등록
Linux 사용자 이름을 확인한다.
whoami아래 예시의 LINUX_USER를 위 명령으로 확인한 실제 사용자 이름으로 바꾼다.
sudo nano /etc/systemd/system/finereport.service다음 내용을 입력한다.
[Unit]
Description=FineReport 11 Tomcat Server
After=network.target
[Service]
Type=forking
User=LINUX_USER
Group=LINUX_USER
Environment=JAVA_HOME=/home/LINUX_USER/apps/tomcat-linux_KO/jdk
Environment=JRE_HOME=/home/LINUX_USER/apps/tomcat-linux_KO/jdk/jre
Environment=CATALINA_PID=/home/LINUX_USER/apps/tomcat-linux_KO/temp/tomcat.pid
ExecStart=/home/LINUX_USER/apps/tomcat-linux_KO/bin/startup.sh
ExecStop=/home/LINUX_USER/apps/tomcat-linux_KO/bin/shutdown.sh
PIDFile=/home/LINUX_USER/apps/tomcat-linux_KO/temp/tomcat.pid
Restart=on-failure
RestartSec=5
TimeoutStartSec=180
TimeoutStopSec=60
UMask=0027
[Install]
WantedBy=multi-user.targetnano에서는 Ctrl+O, Enter, Ctrl+X 순서로 저장하고 종료한다.
서비스 설정을 적용하고 FineReport를 시작한다.
sudo systemctl daemon-reload
sudo systemctl enable --now finereport상태를 확인한다.
sudo systemctl status finereport --no-pager다음처럼 표시되면 정상이다.
Active: active (running)systemd 서비스는 Ubuntu WSL 인스턴스가 시작될 때 실행된다. Windows 로그인만으로 WSL이 항상 자동 실행되는 것은 아니다.
8. 접속 확인
WSL 내부에서 먼저 확인한다.
curl -I http://127.0.0.1:8080/webroot/decision정상이라면 200 또는 302 응답이 나온다.
HTTP/1.1 302
Location: /webroot/decision/login/initialization302는 초기 설정 페이지로 이동시키는 정상 응답이다.
Windows 브라우저에서 먼저 다음 주소를 시도한다.
http://localhost:8080/webroot/decisionlocalhost 접속이 되지 않으면 WSL IP를 확인한다.
hostname -IWindows 브라우저에서 다음 형식으로 접속한다.
http://WSL_IP:8080/webroot/decision예시:
http://172.x.x.x:8080/webroot/decisionWSL IP는 재부팅이나
wsl --shutdown이후 변경될 수 있다. 공개 글에는 실제 WSL IP를 그대로 올리지 않는 것이 좋다.
9. 초기 설정
처음 접속하면 FineReport 초기 설정 화면이 열린다.
- 관리자 계정과 비밀번호 설정
- 배포 환경 확인
- 설정 데이터베이스 선택
- 초기화 완료 후 로그인
로컬 테스트 환경에서는 내장 FineDB를 사용할 수 있다. 실제 운영 환경에서는 PostgreSQL, MySQL 등 별도의 외부 설정 데이터베이스 사용을 권장한다.
관리자 계정, 비밀번호, 라이선스 코드, 데이터베이스 주소와 비밀번호는 블로그나 화면 캡처에 노출하지 않는다.
10. 자주 사용하는 관리 명령어
# 시작
sudo systemctl start finereport
# 종료
sudo systemctl stop finereport
# 재시작
sudo systemctl restart finereport
# 상태 확인
sudo systemctl status finereport --no-pager
# 자동 시작 활성화
sudo systemctl enable finereport
# 자동 시작 해제
sudo systemctl disable finereportsystemd 서비스를 등록한 뒤에는 startup.sh를 별도로 실행하지 않는다. 서버가 중복 실행되면 포트 및 FineDB 잠금 충돌이 발생할 수 있다.
11. 로그 확인
Tomcat 실시간 로그:
tail -f ~/apps/tomcat-linux_KO/logs/catalina.out최근 로그 100줄:
tail -n 100 ~/apps/tomcat-linux_KO/logs/catalina.outsystemd 로그:
sudo journalctl -u finereport --no-pager실시간 systemd 로그:
sudo journalctl -u finereport -f실시간 로그 보기는 Ctrl+C로 종료한다.
12. FineDB db.lck 오류 해결
다음과 같은 오류가 발생할 수 있다.
내장 데이터베이스 연결에 실패했습니다.
WEB-INF/embed/finedb 디렉터리 아래의 db.lck 파일을 삭제하십시오.FineReport가 중복 실행됐거나 비정상 종료되어 이전 프로세스가 내장 DB를 사용 중일 때 주로 발생한다.
실행 중인 FineReport 프로세스가 있는 상태에서
db.lck를 삭제하면 안 된다.
먼저 서비스를 중지한다.
sudo systemctl stop finereportTomcat 프로세스가 남아 있는지 확인한다.
ps -ef | grep '[o]rg.apache.catalina.startup.Bootstrap'프로세스가 남아 있다면 PID를 확인하고 정상 종료 신호를 보낸다.
sudo kill -TERM PID_NUMBER프로세스와 포트가 모두 종료됐는지 다시 확인한다.
ps -ef | grep '[o]rg.apache.catalina.startup.Bootstrap'
ss -ltnp | grep ':8080 '두 명령 모두 아무것도 출력하지 않을 때만 잠금 파일을 처리한다.
cd ~/apps/tomcat-linux_KO/webapps/webroot/WEB-INF/embed/finedbdb.lck가 남아 있다면 삭제 대신 백업 이름으로 이동한다.
if [ -f db.lck ]; then
mv db.lck "db.lck.stale.$(date +%Y%m%d-%H%M%S)"
fiFineReport를 다시 시작하고 응답을 확인한다.
sudo systemctl start finereport
sudo systemctl status finereport --no-pager
curl -I http://127.0.0.1:8080/webroot/decision13. 프로세스와 포트 점검
Tomcat 프로세스 확인:
ps -ef | grep '[o]rg.apache.catalina.startup.Bootstrap'8080 포트 확인:
ss -ltnp | grep ':8080 'FineDB 잠금 파일을 사용 중인 프로세스 확인:
fuser -v \
~/apps/tomcat-linux_KO/webapps/webroot/WEB-INF/embed/finedb/db.lckFineReport는 운영 모니터링을 위한 Java 하위 프로세스를 별도로 실행할 수 있다. Java 프로세스가 여러 개 보인다고 해서 반드시 Tomcat 중복 실행은 아니다. Tomcat 중복 여부는 org.apache.catalina.startup.Bootstrap 프로세스 개수로 판단한다.
14. 콘솔 디버깅
콘솔에서 직접 로그를 보며 실행하려면 먼저 systemd 서비스를 중지한다.
sudo systemctl stop finereport그다음 콘솔 모드로 실행한다.
cd ~/apps/tomcat-linux_KO
JAVA_HOME="$PWD/jdk" \
JRE_HOME="$PWD/jdk/jre" \
./bin/catalina.sh run디버깅이 끝나면 Ctrl+C로 종료하고 systemd 서비스를 다시 시작한다.
sudo systemctl start finereport15. 주요 경로
| 용도 | 경로 |
|---|---|
| 서버 루트 | ~/apps/tomcat-linux_KO |
| Tomcat 설정 | ~/apps/tomcat-linux_KO/conf |
| FineReport 프로젝트 | ~/apps/tomcat-linux_KO/webapps/webroot |
| 보고서 파일 | ~/apps/tomcat-linux_KO/webapps/webroot/WEB-INF/reportlets |
| 내장 FineDB | ~/apps/tomcat-linux_KO/webapps/webroot/WEB-INF/embed/finedb |
| Tomcat 로그 | ~/apps/tomcat-linux_KO/logs |
| systemd 서비스 | /etc/systemd/system/finereport.service |
명령 예시에 필요한 값은 WINDOWS_USER, LINUX_USER, WSL_IP, PID_NUMBER와 같은 표기로 대체하는 것이 안전하다.
