2. KADA REST API 설치#
KADA(Key-optimized Altibase Document Access)는 사용자 환경에 따라 독립 실행 방식(Standalone) 또는 WAS 배포 방식으로 설치할 수 있다. KADA REST API 전체 스펙은 Swagger UI를 통해 대화식으로 확인하고 테스트할 수 있다.
2.1 설치 전 확인 사항#
설치 전에 아래 구성 요소가 준비되었는지 확인한다.
- Altibase Server: Altibase 8.1 이상(JSON 함수 지원 필요) 버전이 설치되어 있어야 하며, 서버가 실행 중 이어야 한다.
- Java: Java 17 이상 버전이 설치되어 있어야 한다.
- 네트워크: REST API 에서 Altibase 서버로 접근이 가능해야 한다.
- 설치 파일 : document-access-rest-{version}-ALL.zip 파일이 준비되어 있어야 한다.
2.2 환경 변수 설정#
2.2.1 필수 환경 변수#
데이터베이스 연결#
| 변수명 | 설명 |
|---|---|
| KADA_ALTIBASE_HOST | Altibase 서버 호스트 |
| KADA_ALTIBASE_PORT | Altibase 서버 포트 |
| KADA_ALTIBASE_DBNAME | 데이터베이스 이름 |
| KADA_ALTIBASE_SYS_PASSWORD | SYS 계정 비밀번호 |
KADA 계정#
| 변수명 | 설명 |
|---|---|
| KADA_API_ADMIN_PASSWORD | KADA admin 계정 비밀번호 |
| KADA_API_USER_PASSWORD | KADA user 계정 비밀번호 |
인증 설정#
| 인증 방식 | 변수명 | 설명 |
|---|---|---|
| 공통 | AUTH_PROVIDER | 인증 방식을 지정(LOCAL 또는 IDP), 생략가능(기본값: LOCAL) |
| Local | JWT_SECRET | JWT 서명을 위한 비밀 키 (256비트 이상으로 설정) |
| IdP | IDP_ISSUER_URI | IdP 발행자(Issuer) URI (예: https://dev-abc.auth0.com/, 끝에 / 포함) |
| IdP | IDP_JWK_SET_URI | IdP의 JSON Web Key Set(JWKS) URI (예: https://dev-abc.auth0.com/.well-known/jwks.json) |
JWT Secret 키 생성 명령어
-
Linux / macOS (Bash)
openssl rand -base64 32 -
Windows (PowerShell)
[Convert]::ToBase64String((1..32 | % { [byte](Get-Random -Max 256) }))
2.2.2 선택 환경 변수#
| 변수명 | 설명 | 기본값 |
|---|---|---|
| SERVER_PORT | KADA REST API 포트 | 8080 |
| SERVER_SERVLET_CONTEXT_PATH | KADA REST API 기본 경로(Base URL) | /api |
| KADA_AUTO_SETUP_ENABLED | KADA REST API 설치에서 독립 실행 방식(Standalone)으로 설치 시, 데이터베이스 설정을 자동으로 설정할지 여부를 결정하는 프로퍼티 (2.3 설치 절차의 2.2.1 독립 실행 방식 - 2단계를 참고한다.) | true |
| SWAGGER_ENABLED | Swagger UI 활성화여부를 설정하는 프로퍼티 (2.5 Swagger UI를 참고 한다.) | false |
2.3 설치 절차#
패키지 파일을 먼저 압축 해제한 다음, 배포 방식에 따라 아래 절차를 진행한다.
unzip document-access-rest-1.0.0-ALL.zip
패키지 구조는 아래와 같다.
document-access-rest-{version}-ALL/ ├── document-access-rest-{version}.war # 실행 파일 └── scripts/ └── database/ └── rest/ ├── install.sh # DB 설치 (Unix/Linux/macOS) ├── install.bat # DB 설치 (Windows) └── create-admin.sh # 관리자 API 키 생성
2.3.1 독립 실행 방식(Standalone)#
별도의 미들웨어 설치 없이 즉시 KADA REST API를 실행하는 방식이다.
1단계: 환경 변수 설정#
데이터베이스 연결 정보와 KADA 계정 비밀번호(KADA_API_ADMIN_PASSWORD, KADA_API_USER_PASSWORD), 인증 방식을 환경변수로 설정한다.
인증 방식은 AUTH_PROVIDER 환경 변수로 지정하며, 설정 값에 따라 추가 환경 변수가 필요하다.
- Local 모드:
AUTH_PROVIDER=LOCAL(기본값, 생략 가능),JWT_SECRET설정 필요 - 외부 IdP 연동:
AUTH_PROVIDER=IDP,IDP_ISSUER_URI,IDP_JWK_SET_URI설정 필요
아래는 인증 방식과 운영 환경에 따라 환경변수를 설정한 예시이다. 환경 변수에 대한 설명은 2.2 환경변수 설정을 참고한다.
예시: Local 모드 (내장 JWT 사용, 기본값)#
Linux
# 필수 DB 연결 설정
export KADA_ALTIBASE_HOST=localhost
export KADA_ALTIBASE_PORT=20300
export KADA_ALTIBASE_DBNAME=mydb
export KADA_ALTIBASE_SYS_PASSWORD=manager
# KADA 계정 비밀번호
export KADA_API_ADMIN_PASSWORD=manager
export KADA_API_USER_PASSWORD=manager
# 인증 설정 (LOCAL 모드)
export JWT_SECRET=your-secure-random-secret-key-at-least-256-bits
Windows
# 필수 DB 연결 설정
$env:KADA_ALTIBASE_HOST="localhost"
$env:KADA_ALTIBASE_PORT="20300"
$env:KADA_ALTIBASE_DBNAME="mydb"
$env:KADA_ALTIBASE_SYS_PASSWORD="manager"
# KADA 계정 비밀번호
$env:KADA_API_ADMIN_PASSWORD="manager"
$env:KADA_API_USER_PASSWORD="manager"
# 인증 설정 (LOCAL 모드)
$env:JWT_SECRET="your-secure-random-secret-key-at-least-256-bits"
예시: IdP 모드 (외부 IdP 연동)#
Linux
# 필수 DB 연결 설정
export KADA_ALTIBASE_HOST=localhost
export KADA_ALTIBASE_PORT=20300
export KADA_ALTIBASE_DBNAME=mydb
export KADA_ALTIBASE_SYS_PASSWORD=manager
# KADA 계정 비밀번호
export KADA_API_ADMIN_PASSWORD=manager
export KADA_API_USER_PASSWORD=manager
# 인증 설정 (IdP 모드)
export AUTH_PROVIDER=IDP
export IDP_ISSUER_URI=https://dev-abc.auth0.com/
export IDP_JWK_SET_URI=https://dev-abc.auth0.com/.well-known/jwks.json
Windows
# 필수 DB 연결 설정
$env:KADA_ALTIBASE_HOST="localhost"
$env:KADA_ALTIBASE_PORT="20300"
$env:KADA_ALTIBASE_DBNAME="mydb"
$env:KADA_ALTIBASE_SYS_PASSWORD="manager"
# KADA 계정 비밀번호
$env:KADA_API_ADMIN_PASSWORD="manager"
$env:KADA_API_USER_PASSWORD="manager"
# 인증 설정 (IdP 모드)
$env:AUTH_PROVIDER="IDP"
$env:IDP_ISSUER_URI="https://dev-abc.auth0.com/"
$env:IDP_JWK_SET_URI="https://dev-abc.auth0.com/.well-known/jwks.json"
2단계: 데이터베이스 설정#
자동 설정 (권장)#
환경 변수 KADA_AUTO_SETUP_ENABLED의 기본값을 true로 설정하면, 별도의 설정 없이 KADA REST API를 시작하면 필요한 DB객체가 자동으로 생성된다.
export KADA_AUTO_SETUP_ENABLED=true
수동 설정#
export KADA_AUTO_SETUP_ENABLED=false
DB 객체를 직접 생성하거나 자동 설치를 사용하지 않는 경우에는 KADA_AUTO_SETUP_ENABLED를 false로 설정한 후 아래의 스크립트를 수동으로 실행한다.
REST API 설치 디렉토리 기준으로 아래 스크립트를 수행한다.
# Unix/Linux/macOS
cd document-access-rest-{version}-ALL/scripts/database/rest
./install.sh
# Windows
cd document-access-rest-{version}-ALL\scripts\database\rest
install.bat
스크립트가 정상적으로 수행될 경우, 아래와 같이 "Installation completed successfully!" 를 확인할 수 있다.
.....생략 .....
[SUCCESS] All installation steps completed!
============================================================
Starting installation verification...
============================================================
[SUCCESS] User account verified: kada_api_admin
[SUCCESS] Table verified: collection_metadata
[SUCCESS] Index verified: idx_collection_created
[SUCCESS] TYPESET verified: dbms_kada_types
[SUCCESS] Package verified: dbms_kada
============================================================
[SUCCESS] All installation verification completed!
============================================================
[SUCCESS] User account verified: kada_api_user
[SUCCESS] Table verified: api_keys
[SUCCESS] Index verified: idx_api_keys_active
[SUCCESS] Index verified: idx_api_keys_role
============================================================
[SUCCESS] All installation verification completed!
============================================================
[INFO] Database connection closed
[SUCCESS] Installation completed successfully!
만약, Altibase 서버가 실행 중이지 않거나 접속할 수 없는 상태인 경우, 아래와 같은 오류가 발생할 수 있다. 이 경우 Altibase 서버가 실행 중인지 확인하고, REST API 서버에서 DB 서버로의 네트워크 접속이 가능한지 점검한다.
... 생략 ...
============================================================
Altibase Document API REST API Installation
============================================================
[INFO] JDBC driver loaded
[ERROR] Installation error: Failed to connect to the database.
java.sql.SQLException: Failed to connect to the database.
at com.altibase.document.installer.DatabaseConnection.<init>(DatabaseConnection.java:38)
at com.altibase.document.installer.BaseInstaller.install(BaseInstaller.java:60)
at com.altibase.document.installer.BaseInstaller.runInstallationAndExit(BaseInstaller.java:321)
at com.altibase.document.installer.RestApiInstaller.main(RestApiInstaller.java:214)
at com.altibase.document.rest.AltibaseDocumentRestApplication.main(AltibaseDocumentRestApplication.java:30)
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77)
at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.base/java.lang.reflect.Method.invoke(Method.java:568)
at org.springframework.boot.loader.launch.Launcher.launch(Launcher.java:102)
at org.springframework.boot.loader.launch.Launcher.launch(Launcher.java:64)
at org.springframework.boot.loader.launch.WarLauncher.main(WarLauncher.java:53)
Caused by: java.sql.SQLException: Communication link failure: Connection refused
at Altibase.jdbc.driver.ex.Error.throwCommunicationErrorException(Error.java:278)
at Altibase.jdbc.driver.cm.CmTcpSocket.open(CmTcpSocket.java:55)
at Altibase.jdbc.driver.cm.CmChannel.open(CmChannel.java:545)
at Altibase.jdbc.driver.cm.CmChannel.openWithName(CmChannel.java:492)
at Altibase.jdbc.driver.cm.CmChannel.open(CmChannel.java:464)
at Altibase.jdbc.driver.AltibaseConnection.<init>(AltibaseConnection.java:136)
at Altibase.jdbc.driver.AltibaseDriver.createConnection(AltibaseDriver.java:70)
at Altibase.jdbc.driver.AltibaseDriver.connect(AltibaseDriver.java:65)
at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:681)
at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:190)
at com.altibase.document.installer.DatabaseConnection.<init>(DatabaseConnection.java:35)
... 11 more
Caused by: java.net.ConnectException: Connection refused
at java.base/sun.nio.ch.Net.connect0(Native Method)
at java.base/sun.nio.ch.Net.connect(Net.java:579)
at java.base/sun.nio.
ch.NioSocketImpl.connect(NioSocketImpl.java:593)
at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
at java.base/java.net.Socket.connect(Socket.java:633)
at Altibase.jdbc.driver.cm.CmTcpSocket.connectTcpSocket(CmTcpSocket.java:84)
at Altibase.jdbc.driver.cm.CmTcpSocket.open(CmTcpSocket.java:49)
... 20 more
[ERROR] Installation failed.
3단계: KADA REST API 서버 구동#
java -jar 명령어로 실행한다.
cd document-access-rest-{version}-ALL/
java -jar document-access-rest-{version}.war
KADA REST API 서버가 정상적으로 구동되면, 서버 시작 로그에서 아래의 메시지를 확인할 수 있다. LOCAL 모드를 사용하는 경우 2.4 초기 관리자 API Key 생성을 참고하여 관리자 API Key를 생성한다.
- 서버 시작 로그
2026-04-10T14:23:29.262+09:00 INFO 30627 --- [document-access-rest] [ main] c.a.d.r.config.DatabaseSetupValidator : Data base setup validation passed
2026-04-10T14:23:29.264+09:00 INFO 30627 --- [document-access-rest] [ main] com.zaxxer.hikari.HikariDataSource : Hika riPool-1 - Starting...
2026-04-10T14:23:29.274+09:00 INFO 30627 --- [document-access-rest] [ main] com.zaxxer.hikari.pool.HikariPool : Hika riPool-1 - Added connection Altibase.jdbc.driver.AltibaseConnection@20524816
2026-04-10T14:23:29.277+09:00 INFO 30627 --- [document-access-rest] [ main] com.zaxxer.hikari.HikariDataSource : Hika riPool-1 - Start completed.
2026-04-10T14:23:29.292+09:00 INFO 30627 --- [document-access-rest] [ main] c.a.d.rest.service.SetupTokenService : Setu p token generated. Token will expire in 30 minutes.
+------------------------------------------------------------------+
| Altibase Document Access REST API |
| Server started on port 8080 |
| |
| [!] INITIAL SETUP REQUIRED |
| |
| No admin API keys found in database. |
| Please complete initial setup via Admin UI: |
| |
| URL: http://localhost:8080/api |
| Admin UI: http://localhost:8080/api/admin-ui |
| |
| Setup Token: SETUP-46d183de-100f-423f-a2b1-52bdea75f10e |
| |
| [!] Token expires at: 2026-04-10 14:53:29 |
| [!] Token is valid only for this server instance |
| |
| Alternative: Use create-admin.sh script |
+------------------------------------------------------------------+
2026-04-10T14:23:29.293+09:00 INFO 30627 --- [document-access-rest] [ main] c.a.d.rest.config.SetupTokenInitializer : Setup token generated. Complete initial setup via Admin UI or create-admin.sh script.
2.3.2 WAS 배포 방식#
Jakarta EE 9+를 지원하는 Tomcat 10.x, WildFly 27+ 등에 배포한다.
1단계: 환경 변수 설정(Tomcat setenv.sh)#
인증 방식에 따라 필요한 환경 변수를 $CATALINA_HOME/bin/setenv.sh 파일에 설정한다.
export KADA_ALTIBASE_HOST=localhost
export KADA_ALTIBASE_PORT=20300
export KADA_ALTIBASE_DBNAME=mydb
export KADA_ALTIBASE_SYS_PASSWORD=manager
export KADA_API_ADMIN_PASSWORD=manager
export KADA_API_USER_PASSWORD=manager
# Local 모드 설정 예시
export AUTH_PROVIDER=LOCAL
export JWT_SECRET=your-secure-jwt-secret-key-at-least-256-bits
2단계: WAR 파일 배포#
cp document-access-rest-{version}.war $CATALINA_HOME/webapps/
3단계: WAS 시작#
WAS가 정상적으로 시작되었는지 확인한다. LOCAL 모드를 사용하는 경우 2.4 초기 관리자 API Key 생성을 참고하여 관리자 API Key를 생성한다.
2.4 초기 관리자 API Key 생성(LOCAL 모드 전용)#
Note
LOCAL 모드에서는 KADA REST API 최초 시작 시 관리자 API Key를 생성해야 한다. 반면, IDP 모드에서는 이 단계가 필요 없다.
서버 시작 로그에서 Setup Token 을 확인하여 Admin UI(http://localhost:8080/api/admin-ui)에서 관리자 API Key를 생성한다.
- 서버 시작 로그
+------------------------------------------------------------------+
| Altibase Document Access REST API |
| Server started on port 8080 |
| |
| [!] INITIAL SETUP REQUIRED |
| |
| No admin API keys found in database. |
| Please complete initial setup via Admin UI: |
| |
| URL: http://localhost:8080/api |
| Admin UI: http://localhost:8080/api/admin-ui |
| |
| Setup Token: SETUP-d9c1638f-946c-490d-bd7b-f45f3d272671 |
| |
| [!] Token expires at: 2026-01-07 11:18:03 |
| [!] Token is valid only for this server instance |
+------------------------------------------------------------------+
- 브라우저에서 http://localhost:8080/api/admin-ui 접속
- 로그에서 확인한 Setup Token 입력
- Admin Client ID와 Description 입력하여 API Key 생성
2.5 Swagger UI 설정#
Swagger UI는 REST API를 브라우저에서 직접 호출하고 테스트할 수 있도록 제공되는 대화형 API 문서 도구이다.
Swagger UI는 보안상 기본적으로 비활성화되어 있으며, 환경 변수 또는 Java 시스템 프로퍼티를 통해 활성화할 수 있다.
Swagger UI 활성화 설정#
환경 변수로 설정#
export SWAGGER_ENABLED=true
export API_DOCS_ENABLED=true
참고: 환경 변수 설명
| 환경변수 | 기본값 | 설명 |
|---|---|---|
| SWAGGER_ENABLED | false | Swagger UI 활성화 |
| API_DOCS_ENABLED | false | OpenAPI JSON 스펙 활성화 |
Java 시스템 프로퍼티로 설정#
java -DSWAGGER_ENABLED=true -DAPI_DOCS_ENABLED=true -jar document-access-rest-{version}.jar
Warning
운영 환경에서는 Swagger UI를 비활성화하거나 인증된 사용자만 접근할 수 있도록 네트워크 수준에서 제한하는 것을 권장한다.
Swagger UI 접속#
서버 관리자가 Swagger UI를 활성화한 경우 다음 URL로 접속한다:
| URL | 설명 |
|---|---|
| /api/swagger-ui.html | Swagger UI (대화형 API 문서) |
| /api/v3/api-docs | OpenAPI 3.0 JSON 스펙 |
예시 URL
http://localhost:8080/api/swagger-ui.html
http://localhost:8080/api/v3/api-docs
2.6 보안 주의 사항#
JWT_SECRET 보안#
LOCAL 모드에서는 JWT_SECRET을 반드시 256비트 이상의 강력한 키로 설정해야 한다. 기준을 충족하지 않을 경우 서버 기동에 실패할 수 있다.
IdP연동 권장#
운영 환경이거나 외부 IdP(예: Auth0, Okta)를 사용하는 경우 IDP 모드 사용을 권장한다.
Setup Token 만료#
초기 설정을 위한 Setup Token은 발급 후 30분이 지나면 자동으로 만료되며, 한 번 사용하면 즉시 무효화된다.