# Installation Guide

This document applies to both the Personal Edition and Enterprise Edition software installation. The installation methods for both editions are identical!!!

Please download the installation package first. Default account: admin/admin.

To help you understand the properties that need to be configured during installation, please first learn about the log monitoring related functional design.

# Local Standalone Deployment

# Prerequisites

Depends on Java environment. Install JDK on the server first and configure environment variables. Recommended versions: JDK8 or JDK11.
Download the installation package and extract it to the directory where you want to install.
If it's a Linux server, you need to install OpenSSL 3. Please refer to here.

Most newer versions of Linux systems have installed with OpenSSL 3 by default. You can check the OpenSSL version using the openssl version command.

# Configure Properties

Modify the following configurations in the conf/application.properties file:

# API context
dbapi.api.context=api

# If the database address is not modified, it will default to using the built-in embedded metadata database SQLite
# Metadata database address, can use MySQL or the built-in SQLite
spring.datasource.dynamic.datasource.meta-db.driver-class-name=org.sqlite.JDBC
spring.datasource.dynamic.datasource.meta-db.url=jdbc:sqlite::resource:sqlite.db
spring.datasource.dynamic.datasource.meta-db.username=
spring.datasource.dynamic.datasource.meta-db.password=

# Method for writing API access logs to the log database (recommended ClickHouse). Values can only be db/kafka/null
# db means DBAPI connects directly to the log database and writes API access logs directly to the log database
# kafka means DBAPI writes API access logs to Kafka, users need to collect logs from Kafka and write them to the log database themselves
# null means DBAPI only writes API access logs to local disk file (logs/dbapi-access.log), users need to collect logs from disk files and write them to the log database
access.log.writer=null

# Log database address, recommended to use ClickHouse. If you don't need to use the monitoring functions on the page, you don't need to configure the log database address
spring.datasource.dynamic.datasource.access-log-db.driver-class-name=ru.yandex.clickhouse.ClickHouseDriver
spring.datasource.dynamic.datasource.access-log-db.url=jdbc:clickhouse://127.0.0.1:8123/default
spring.datasource.dynamic.datasource.access-log-db.username=default
spring.datasource.dynamic.datasource.access-log-db.password=123456

# If access.log.writer=kafka is configured, you also need to configure the Kafka address and the topic for log writing
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

If MySQL is configured as the metadata database, please execute the initialization script sql/ddl_mysql.sql in MySQL first.

If a log database address is configured, please execute the initialization script in the log database first. DBAPI provides scripts for ClickHouse and MySQL: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql.

If MySQL is used as the log database, we don't recommend using the same physical MySQL as the metadata database. Try to separate them and use another physical MySQL instance.

(Optional) Configure automatic log cleanup

Only supported in the Enterprise Edition software.

If you're using a log database, you can configure automatic cleanup of logs in the log database. Modify the following configurations in the conf/application.properties file:

# Whether to enable automatic cleanup, disabled by default
# Enable or disable automatic cleanup of access logs (true/false)
access.log.autoClean.enable=false

# Cleanup task scheduling time, defaults to execution at 3:00 AM every day
# Cron expression for scheduling the access log cleanup task (executes daily at 3:00 AM by default)
access.log.autoClean.cron=0 0 3 * * ?

# Maximum retention days for log data, defaults to 15 days
# Number of days to retain access logs before cleanup (15 days by default)
access.log.autoClean.retention.days=15

(Optional) Modify port number

Modify server.port in the conf/application-standalone.properties file:

server.port=8520

(Optional) Modify which IPs can access the UI webpage

Modify dbapi.ui.allowed.ips in the conf/application-standalone.properties file:

# In standalone mode, configure which IPs can access the UI webpage. If not configured, all IPs can access
dbapi.ui.allowed.ips=

(Optional) Modify memory parameters

Modify the standalone_opts value in the bin/jvm_env.properties file:

#standalone_opts="-Xms1g -Xmx4g -Xmn2g"

You can keep the default without modification.

(Optional) Configure Java command path

If you have installed multiple versions of JDK and need to use a specific version, please configure this item. You can leave it unconfigured. If not configured, it will default to using the java command from environment variables.

Modify the JAVA_LOCATION value in the bin/jvm_env.properties file. Fill in the full path where the java command is located, for example: /usr/bin/java

JAVA_LOCATION="/usr/bin/java"

# Startup Commands

Linux one-click start/stop:

# For Ubuntu/Debian systems, please use bash, not sh
bash bin/dbapi-daemon.sh start standalone
bash bin/dbapi-daemon.sh stop standalone

For easier viewing of logs in the foreground, you can also start in foreground mode:

bash bin/dbapi.sh start standalone

For Windows operating systems, right-click on the bin/dbapi.ps1 file and choose to run with PowerShell.

Note: Windows systems only support standalone mode operation, not cluster mode.
The system will automatically exit on the first startup and needs to be activated. After activation, restart to use.
Access the UI via browser at http://192.168.xx.xx:8520. To prevent cache from previous versions, please press Ctrl+F5 in the browser to force refresh cache.

Must activate! Activate! Activate! A license must be applied for use! A license must be applied for use! A license must be applied for use!

# Local Cluster Deployment

# Cluster Role Description

There are 3 types of service processes in the cluster: manager, gateway, and apiServer.
manager is the management service, i.e., the web UI service. Through this UI service, you can create data sources, groups, and APIs, and manage API online debugging, execution, publishing, and offline operations. There is only one such service process in the entire cluster.
gateway is the gateway service, responsible for distributing API requests to different apiServers. There is only one such service process in the entire cluster.
apiServer is the API service, responsible for receiving API requests and executing the business logic in the APIs. There can be multiple such service processes in the entire cluster.

# Prerequisites

Cluster deployment depends on nacos, mysql, and redis. Please install nacos (recommended version 1.4.2), mysql, and redis first.
Prepare multiple Linux servers, each with JDK installed. Recommended versions: JDK8, JDK11, or JDK14.
Install OpenSSL 3 on each Linux server. Please refer to here.

Most newer versions of Linux systems come with OpenSSL 3 by default. You can check the OpenSSL version using the openssl version command.

The time on all servers must be synchronized

# SSH Passwordless Configuration

Select one machine (host1) as the deployment machine and configure passwordless SSH login from host1 to every other machine:

ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

for ip in host2 host3;     # Please replace host2 host3 with the hostnames of the machines you want to deploy to
do
  ssh-copy-id  $ip   # This operation requires manual input of the deployment user's password
done

# Download and Extract

Download the installation package and extract it to the directory where you want to install on the deployment machine host1.

# Database Initialization

Create a new database in MySQL and execute the initialization script sql/ddl_mysql.sql.

# Configuration Parameters

Modify the following configurations in the conf/application.properties file:

#################################### please config properties below #####################################
# Unified root path for API access, example: http://192.168.xx.xx:8520/api/xxx
# API context
dbapi.api.context=api

# Metadata database address, cluster version can only use MySQL
spring.datasource.dynamic.datasource.meta-db.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.dynamic.datasource.meta-db.url=jdbc:mysql://127.0.0.1:3306/dbapi?useSSL=false&characterEncoding=UTF-8&serverTimezone=GMT%2B8
spring.datasource.dynamic.datasource.meta-db.username=root
spring.datasource.dynamic.datasource.meta-db.password=root

# Method for writing API access logs to the log database (recommended ClickHouse). Values can only be db/kafka/null
# db means DBAPI connects directly to the log database and writes API access logs directly to the log database
# kafka means DBAPI writes API access logs to Kafka, users need to collect logs from Kafka and write them to the log database themselves
# null means DBAPI only writes API access logs to local disk file (logs/dbapi-access.log), users need to collect logs from disk files and write them to the log database
access.log.writer=null

# Log database address, recommended to use ClickHouse. If you don't need to use the monitoring functions on the page, you don't need to configure the log database address
spring.datasource.dynamic.datasource.access-log-db.driver-class-name=ru.yandex.clickhouse.ClickHouseDriver
spring.datasource.dynamic.datasource.access-log-db.url=jdbc:clickhouse://127.0.0.1:8123/default
spring.datasource.dynamic.datasource.access-log-db.username=default
spring.datasource.dynamic.datasource.access-log-db.password=123456

# If access.log.writer=kafka is configured, you also need to configure the Kafka address and the topic for log writing
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

############################## if cluster, please config properties below ##############################

# Nacos address, needed if cluster mode
spring.cloud.nacos.server-addr=127.0.0.1:8848
spring.cloud.nacos.discovery.username=nacos
spring.cloud.nacos.discovery.password=nacos
spring.cloud.nacos.discovery.namespace=public

# Redis address, needed if cluster mode
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.password=

If a log database address is configured, please execute the initialization script in the log database first. DBAPI provides scripts for ClickHouse and MySQL: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql.

If MySQL is used as the log database, we don't recommend using the same physical MySQL as the metadata database. Try to separate them and use another physical MySQL instance.

(Optional) Configure automatic log cleanup

Only supported in the Enterprise Edition software.

If you're using a log database, you can configure automatic cleanup of logs in the log database. Modify the following configurations in the conf/application.properties file:

# Whether to enable automatic cleanup, disabled by default
# Enable or disable automatic cleanup of access logs (true/false)
access.log.autoClean.enable=false

# Cleanup task scheduling time, defaults to execution at 3:00 AM every day
# Cron expression for scheduling the access log cleanup task (executes daily at 3:00 AM by default)
access.log.autoClean.cron=0 0 3 * * ?

# Maximum retention days for log data, defaults to 15 days
# Number of days to retain access logs before cleanup (15 days by default)
access.log.autoClean.retention.days=15

(Optional) Modify port numbers

Modify the gateway port number in server.port in the conf/application-gateway.yml file:

server:
  port: 8525

Modify the manager port number in server.port in the conf/application-manager.properties file:

server.port=8523

Modify the apiServer port number in server.port in the conf/application-apiServer.properties file:

server.port=8524

(Optional) Modify memory parameters

Modify the manager_opts, apiServer_opts, and gateway_opts values in the bin/jvm_env.properties file:

# JVM parameter configuration for manager in cluster deployment
#manager_opts="-Xms512m -Xmx1g -Xmn512m"

# JVM parameter configuration for apiServer in cluster deployment
#apiServer_opts="-Xms1g -Xmx4g -Xmn2g"

# JVM parameter configuration for gateway in cluster deployment
#gateway_opts="-Xms1g -Xmx4g -Xmn2g"

You can keep the default without modification.

(Optional) Configure Java command path

For the cluster version, we strongly recommend configuring this item because the cluster startup script uses SSH to execute java commands remotely, but when SSH executes commands remotely, it doesn't load environment variable configurations by default, which may cause the system to not recognize the java command.

Modify the JAVA_LOCATION value in the bin/jvm_env.properties file. Fill in the full path where the java command is located, for example: /usr/bin/java

JAVA_LOCATION="/usr/bin/java"

Modify the conf/install_config.conf file to configure the machine nodes to be installed:

# All host IPs or hostnames where DBAPI will be installed, separated by commas
ips=host1,host2,host3

sshPort=22

# Host to install gateway
gateway=host1

# Hosts to install apiServer, multiple separated by commas
apiServers=host1,host2,host3

# Host to install manager
manager=host2

# Copy Installation Files

Copy the installation files from host1 to the same directory on every other machine. You can use a script for one-click copying:

bash bin/scp-host.sh

# Startup Commands

Cluster operation scripts:

# One-click cluster startup
bash bin/start-all.sh

# One-click cluster shutdown
bash bin/stop-all.sh

# One-click check cluster running status
bash bin/status-all.sh

# Manual start/stop of individual services
bash bin/dbapi-daemon.sh start gateway
bash bin/dbapi-daemon.sh start manager
bash bin/dbapi-daemon.sh start apiServer

bash bin/dbapi-daemon.sh stop gateway
bash bin/dbapi-daemon.sh stop manager
bash bin/dbapi-daemon.sh stop apiServer

# Manual foreground startup of individual services (can view logs in command line foreground)
bash bin/dbapi.sh start gateway
bash bin/dbapi.sh start manager
bash bin/dbapi.sh start apiServer

Note: For ubuntu/debian systems, please use the bash command, not the sh command.

The system will automatically exit on the first startup and needs to be activated. After activation, restart to use.
Access the UI via browser at http://192.168.xx.xx:8523. To prevent cache from previous versions, please press Ctrl+F5 in the browser to force refresh cache. APIs are accessed through the gateway at http://192.168.xx.xx:8525/api/xx.

Must activate! Activate! Activate! A license must be applied for use! A license must be applied for use! A license must be applied for use!

# Appendix

Quick Docker installation of Nacos:

docker run --env MODE=standalone --name nacos -d -p 8848:8848 nacos/nacos-server:1.4.2