Installation Guide

This document applies to both the Personal and Enterprise editions of the software, and the installation methods for both editions are identical!!!

Please first download the installation package. The default account is admin/admin.

To help you understand the parameters that need to be configured during installation, please first familiarize yourself with the feature design related to Log Monitoring.

Local Standalone Deployment

Preparation

• A Java environment is required. First install the JDK on the server and configure the environment variables. Recommended versions are JDK8, JDK11, and JDK17.

• Download the installation package and extract it to the desired installation directory.

• If you are using a Linux server, you need to install OpenSSL 3. Please refer to here.

NOTE

Most modern Linux distributions already come with OpenSSL 3 installed. You can use the openssl version command to check the OpenSSL version.

Configuration Parameters

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

# The unified root path for API access URLs, e.g., http://192.168.xx.xx:8520/api/xxx
# API context
dbapi.api.context=api

# If the database address is not modified, the built-in embedded metadata database SQLite will be used by default.
# Metadata database address; you 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=

# The method for writing API access logs to the log database (recommended ClickHouse); the value can only be db/kafka/null.
# 'db' means dbapi directly connects to the log database and writes API access logs directly to the log database.
# 'kafka' means dbapi writes API access logs to Kafka, and users need to collect logs from Kafka and write them to the log database themselves.
# 'null' means dbapi will only write API access logs to a local disk file (logs/dbapi-access.log), and users need to collect logs from the disk file and write them to the log database themselves.
access.log.writer=null

# Log database address; ClickHouse is recommended. If you do not need to use the monitoring features on the UI, you do not 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

IMPORTANT

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

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

IMPORTANT

If the log database uses MySQL, we do not recommend using the same physical MySQL instance as the metadata database. Try to separate them and use a different physical MySQL instance.

• (Optional) Configure automatic log cleanup

If you are 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; executed at 3:00 AM every day by default.
# 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 number of days to retain log data before cleanup; 15 days by default.
# Number of days to retain access logs before cleanup (15 days by default)
access.log.autoClean.retention.days=15

NOTE

Only the Enterprise edition supports this configuration.

• (Optional) Modify the port number

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

server.port=8520

• (Optional) Modify which IP addresses are allowed to access the UI webpage

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

# In standalone mode, configure which IP addresses are allowed to access the UI webpage. If not configured, all IP addresses are allowed to 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 settings without modification.

• (Optional) Configure the Java command path

If you have installed multiple versions of the JDK and need to use a specific version of the JDK, you need to configure this setting. You can choose not to configure it; if you do not configure it, the Java command in the environment variables will be used by default.

Modify the JAVA_LOCATION value in the bin/jvm_env.properties file, and fill in the full path where the Java command is located, such as /usr/bin/java.

JAVA_LOCATION="/usr/bin/java"

Startup Commands

• One-click start/stop for Linux

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

# Restart
bash bin/dbapi-daemon.sh restart standalone
# Check status
bash bin/dbapi-daemon.sh status standalone

To make it easier to view logs in the foreground, you can also start in the foreground:

bash bin/dbapi.sh start standalone

• If you are using Windows, right-click the bin/dbapi.ps1 file and select to run it with PowerShell.

NOTE

Note that Windows systems only support standalone mode and do not support cluster mode.

WARNING

The system will automatically exit upon first startup. You need to activate. After activation, restart the system to use it. You must activate! Activate! Activate! You must apply for a license to use it! You must apply for a license to use it! You must apply for a license to use it!

• Access the UI via the browser at http://192.168.xx.xx:8520

TIP

If you have previously installed and used an earlier version, to prevent cached data from the previous version, please use Ctrl+F5 in your browser to force a cache refresh.

Local Cluster Deployment

Cluster Role Explanation

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

Preparation

• Cluster deployment depends on nacos, mysql, and redis. Please first install nacos (version 1.4.2 is recommended), mysql, and redis.
• Prepare multiple Linux servers, each installing JDK. Recommended versions are JDK8, JDK11, and JDK17.
• Each Linux server must install OpenSSL 3. Please refer to here.

NOTE

Most modern Linux distributions already come with OpenSSL 3 installed. You can use the openssl version command to check the OpenSSL version.

Important Notes

The time on all servers must be synchronized.

If you have enabled a firewall, ensure that the manager can access the gateway and apiServer, and that the gateway can access the apiServer.

SSH Passwordless Configuration

• Select one machine, host1, as the deployment machine, and configure passwordless SSH login from host1 to each of the other machines.

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;     # Replace host2 and host3 here with the hostnames of the machines you want to deploy
do
  ssh-copy-id  $ip   # You need to manually enter the deployment user's password during this operation
done

Download and Extract

• Download the installation package and extract it to the directory where host1 needs to be installed.

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 #####################################
# The unified root path for API access URLs, e.g., http://192.168.xx.xx:8520/api/xxx
# API context
dbapi.api.context=api

# Metadata database address; the cluster edition 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

# The method for writing API access logs to the log database (recommended ClickHouse); the value can only be db/kafka/null.
# 'db' means dbapi directly connects to the log database and writes API access logs directly to the log database.
# 'kafka' means dbapi writes API access logs to Kafka, and users need to collect logs from Kafka and write them to the log database themselves.
# 'null' means dbapi will only write API access logs to a local disk file (logs/dbapi-access.log), and users need to collect logs from the disk file and write them to the log database themselves.
access.log.writer=null

# Log database address; ClickHouse is recommended. If you do not need to use the monitoring features on the UI, you do not 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; required if in 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; required if in cluster mode.
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.password=

IMPORTANT

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

TIP

If the log database uses MySQL, we do not recommend using the same physical MySQL instance as the metadata database. Try to separate them and use a different physical MySQL instance.

Redis Sentinel Mode

If Redis is using Sentinel mode, you need to modify the Redis-related configurations as follows:

spring.redis.sentinel.master=mymaster
spring.redis.sentinel.nodes=192.168.3.10:26379,192.168.3.10:26380,192.168.3.10:26381
spring.redis.password=123456
spring.redis.timeout=2000ms

• (Optional) Configure automatic log cleanup

If you are 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; executed at 3:00 AM every day by default.
# 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 number of days to retain log data before cleanup; 15 days by default.
# Number of days to retain access logs before cleanup (15 days by default)
access.log.autoClean.retention.days=15

NOTE

Only the Enterprise edition supports this configuration.

• (Optional) Modify the port number

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

server:
  port: 8525

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

server.port=8523

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

server.port=8524

CAUTION

If you have enabled a firewall, after modifying the port numbers, make sure to update the firewall settings to ensure that the manager can access the gateway and apiServer, and that the gateway can access the apiServer.

• (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 the manager in cluster deployment
#manager_opts="-Xms512m -Xmx1g -Xmn512m"

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

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

You can keep the default settings without modification.

• (Optional) Configure the Java command path

If you have installed multiple versions of the JDK and need to use a specific version of the JDK, you need to configure this setting. You can choose not to configure it; if you do not configure it, the Java command in the environment variables will be used by default.

Modify the JAVA_LOCATION value in the bin/jvm_env.properties file, and fill in the full path where the Java command is located, such as /usr/bin/java.

JAVA_LOCATION="/usr/bin/java"

WARNING

When deploying the cluster edition, we strongly recommend that you configure this setting, because the cluster startup script will use SSH to remotely execute the Java command. However, when SSH executes commands remotely, the environment variable configuration is not loaded by default, which may result in the system failing to recognize the Java command.

• 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 where the gateway will be installed
gateway=host1

# Hosts where the apiServer will be installed, multiple hosts separated by commas
apiServers=host1,host2,host3

# Host where the manager will be installed
manager=host2

Copy Installation Files

• Copy the installation files from host1 to the same directory on each of the other machines. You can use a script to copy them with one click:

bash bin/scp-host.sh

Startup Commands

• Cluster operation scripts

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

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

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

# Manually start or stop 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

# Manually restart individual services
bash bin/dbapi-daemon.sh restart gateway
bash bin/dbapi-daemon.sh restart manager
bash bin/dbapi-daemon.sh restart apiServer

# Manually start individual services in the foreground (you can view logs in the foreground in the command line)
bash bin/dbapi.sh start gateway
bash bin/dbapi.sh start manager
bash bin/dbapi.sh start apiServer

INFO

Note that if you are using an ubuntu/debian system, please use the bash command instead of the sh command.

WARNING

The system will automatically exit upon first startup. You need to activate. After activation, restart the system to use it. You must activate! Activate! Activate! You must apply for a license to use it! You must apply for a license to use it! You must apply for a license to use it!

• Access the UI via the browser at http://192.168.xx.xx:8523. APIs are accessed through the gateway at http://192.168.xx.xx:8525/api/xx.

TIP

If you have previously installed and used an earlier version, to prevent cached data from the previous version, please use Ctrl+F5 in your browser to force a cache refresh.

Appendix

• Quick Docker installation of Nacos

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