JSP 백엔드
로컬 실행 가이드

이 가이드는 개발 경험이 많지 않은 분을 위해 작성됐어요. 명령어의 의미를 몰라도 괜찮으니, 안내된 순서대로 따라해 주세요.

진행할 작업은 두 가지예요. 컴퓨터에 JDK 17과 Maven을 설치하고, Maven으로 빌드한 결제 서버를 실행해요. 이 문서는 백엔드 서버를 띄우는 가이드이며, 결제 테스트 화면(프론트엔드)은 다루지 않아요.

미리 알아둘 용어

JDK와 Maven을 컴퓨터에 설치해요. 이미 설치되어 있고 버전이 맞는다면 건너뛰어도 돼요.

1. JDK 17 설치

1. 다운로드
   웹 브라우저에서 adoptium.net에 접속한 뒤, Temurin 17 (LTS)를 선택해 설치 파일을 받아 주세요. "Latest LTS release" 버튼이 기본으로 최신 LTS를 가리키므로, 버전이 17인지 확인해 주세요.
2. 설치
   받은 파일을 실행해 설치해요. Windows 인스톨러는 "Set JAVA_HOME variable"과 "Add to PATH" 옵션을 체크하고 진행해 주세요. macOS · Linux는 기본 설정으로 설치하시면 돼요.
3. 설치 확인
   터미널을 새로 열고 아래 명령을 입력해 주세요. 버전 숫자(예: openjdk version "17.x.x")가 표시되면 설치가 완료된 거예요.

   terminal복사

   java -version

2. Apache Maven 설치

1. 다운로드
   웹 브라우저에서 maven.apache.org/download.cgi에 접속한 뒤, Binary zip archive(예: apache-maven-3.x.x-bin.zip)를 받아 주세요.
2. 압축 해제 및 PATH 등록
   받은 zip 파일을 원하는 폴더에 풀어 주세요. 이어서 bin 폴더 경로를 시스템 PATH에 등록해야 해요.

   PATH 등록 안내복사

   # Windows — 시스템 환경 변수 편집
   # 1. 시작 메뉴 → "환경 변수 편집" 검색 → 실행
   # 2. 시스템 변수 > Path 선택 > 편집
   # 3. "새로 만들기" 클릭 후 Maven bin 폴더 경로 입력
   #    예: C:\apache-maven-3.9.9\bin
   # 4. 확인 → 확인 → PowerShell 재시작
   
   # macOS / Linux — 터미널에서 실행
   # ~/.zshrc (zsh) 또는 ~/.bashrc (bash)에 아래 두 줄 추가:
   export M2_HOME="$HOME/apache-maven-3.9.9"
   export PATH="$M2_HOME/bin:$PATH"
   # 저장 후 적용:
   source ~/.zshrc

3. 설치 확인
   터미널을 새로 열고 아래 명령을 입력해 주세요. Maven 버전과 Java 버전이 함께 표시되면 완료예요.

   terminal복사

   mvn -v

이제 서버를 빌드하고 실행해요. 아래 순서를 그대로 따라해 주세요. 명령은 한 줄씩 복사해 터미널에 붙여넣고 Enter를 누르시면 돼요.

1. 터미널 열기
   Windows는 PowerShell, Mac은 터미널 앱을 열어 주세요.
2. 프로젝트 폴더로 이동
   프로젝트를 저장한 폴더 안의 jsp 폴더로 이동해요. 아래의 <프로젝트 폴더> 부분을 본인이 저장한 실제 경로로 바꿔 주세요.

   terminal복사

   cd "<프로젝트 폴더>/jsp"

   경로 입력이 익숙하지 않다면, 터미널에 cd (cd 뒤에 공백 한 칸)를 입력한 뒤 jsp 폴더를 터미널 창으로 드래그해 주세요. 경로가 자동으로 채워져요. Windows는 폴더에서 Shift + 우클릭 → "경로로 복사" 후 붙여넣기 하시면 돼요.
3. 빌드 (최초 1회 또는 코드 변경 시)
   Maven으로 소스를 컴파일하고 kcp-jsp.war 파일을 만들어요.

   terminal복사

   mvn clean package -DskipTests

   최초 실행 시에는 Maven이 인터넷에서 필요한 라이브러리를 모두 다운로드하므로 수 분이 걸릴 수 있어요. BUILD SUCCESS가 표시되면 완료예요.
4. 서버 실행
   빌드된 WAR 파일을 실행해요. 이 명령 하나로 내장 Tomcat이 함께 시작돼요.

   terminal복사

   java -jar target/kcp-jsp.war

5. 서버 실행 확인
   터미널에 Started KcpJspApplication 또는 Tomcat started on port 8080 같은 Spring Boot 시작 로그가 표시되면 서버가 실행된 거예요. 더 확실한 확인 방법은 다음 04를 참고해 주세요.

이 문서는 서버(백엔드) 실행을 위한 가이드예요. 화면(프론트엔드)이 아닌 서버의 정상 실행 여부를 응답으로 확인해요.

확인 방법

방법 1 · 터미널 메시지: 서버를 실행한 터미널에서 Started KcpJspApplication 또는 Tomcat started on port 8080 같은 줄이 보이면 서버가 실행된 거예요.

방법 2 · 응답 확인: 브라우저 주소창에 http://localhost:8080/config를 입력하거나, 새 터미널에서 아래 명령을 실행해 주세요. {"site_cd":"T0000"}와 같은 응답이 표시되면 서버와 라우팅이 정상 동작하는 거예요.

curl http://localhost:8080/config

실행 중 자주 만나게 되는 문제와 해결 방법이에요. 대부분 java·mvn 명령의 PATH 문제이거나, 포트가 이미 사용 중이어서 발생해요.

증상별 해결법

테스트가 끝나면 다음 방법으로 서버를 종료해 주세요.

서버가 동작 중인 터미널 창에서 Ctrl + C를 눌러 주세요. Mac도 동일해요. 서버가 종료되며, 터미널이 다시 명령을 입력할 수 있는 상태로 돌아와요.