Installation and Configuration Guide

← Back | Main Page

This section explains how to install and deploy the FT Device Network Service — a Spring Boot application built with Java 25 and Gradle.

1. System Requirements

  • Java 25 or higher

  • Gradle 7.0 or higher

  • ClickHouse server

2. Getting the Installation Files

Each release contains:

  • ft-device-network-service.jar — executable JAR file for manual deployment

  • hazelcast-client.yml — hazelcast configuration file

  • start.bat|start.sh - start scripts for Windows and Linux

  • app.env - environment variables required by application

3. Environment Configuration

This section explains how to prepare the environment before running the FT Device Network Service. It covers setting up required environment variables. Proper environment preparation is mandatory for a successful operation.

3.1. Setup Environment Variables

Placeholders in the examples must be replaced with real values before you run any commands in app.env or command line.

3.1.1. Main Application Settings

USE_NOHUP

Flag for running the application in the background
Default: 1 (running in background, use 0 for running in terminal)

JAVA_HOME

Java installation path.
Default: /path/to/java/exe/folder

Make sure to specify the Java path without the /bin directory.
SERVER_PORT

The HTTP port where the application will run.
Default: 8383

3.1.2. ClickHouse Database Configuration

CLICKHOUSE_HOST

ClickHouse server host.
Default: localhost

CLICKHOUSE_HTTP_PORT

ClickHouse server port.
Default: 8123

CLICKHOUSE_DATABASE

ClickHouse database name.
Default: ftacs_qoe_ui_data

CLICKHOUSE_USERNAME

ClickHouse username.
Default: ftacs

CLICKHOUSE_PASSWORD

ClickHouse password.
Default: ftacs

3.1.3. Hazelcast Configuration

HZ_CONFIG_PATH

Path to the Hazelcast client configuration file.
Default: /path/to/current/folder/hazelcast-client.yml

3.2. Hazelcast Cluster Configuration

The application uses Hazelcast for distributed caching and cluster coordination. (the same one as ACS uses) Hazelcast client configuration is defined in hazelcast-client.yml and can be customized.

Cluster members parameter should be configured to the same HC cluster members as ACS uses
In case of using the ACS without dedicated HC (built-in mode), it should be configured as: ACS_IP:5700
Syntax:

cluster-members:
- 10.0.0.1:5701
- 10.0.0.2:5701

3.2.1. Sample Configuration File

Below is a sample Hazelcast client configuration that can be customized according to your environment:

Unresolved include directive in modules/ROOT/pages/installation.adoc - include::../src/main/resources/hazelcast-client.yml[]
Hazelcast Production Setup

  • For production deployments, always specify at least 2-3 cluster members for high availability

  • Configure proper timeouts based on your network conditions

  • Consider enabling TLS for secure communication between nodes

4. ClickHouse Database Setup

The FT Device Network Service uses ClickHouse for high-performance time-series data storage. To keep the data isolated and well-organized, it is recommended to create a dedicated ClickHouse database and a separate user if they do not exist. Ensure that your environment variables (e.g. CLICKHOUSE_HOST, CLICKHOUSE_DATABASE, CLICKHOUSE_USERNAME, and CLICKHOUSE_PASSWORD) are set accordingly.

Requires network_ch_tables.sql manually execution.

More details about the project database you can read here

4.1. Performance Tuning (perfomance tuning, used only by developers)

TASK_CORE_POOL_SIZE

Task executor core pool size.
Default: 10

TASK_MAX_POOL_SIZE

Task executor max pool size.
Default: 20

TASK_QUEUE_CAPACITY

Task executor queue capacity.
Default: 500

DATA_PROCESSING_BATCH_SIZE

Data processing batch size.
Default: 100

DATA_PROCESSING_TIMEOUT_SECONDS

Data processing timeout.
Default: 30

Minimum variables you must change

  • CLICKHOUSE_HOST, CLICKHOUSE_USERNAME, CLICKHOUSE_PASSWORD

  • HZ_CONFIG_PATH

All initial and additional liquibase scripts need to install manually.

5. Run & Verify

After launching the application, verify it’s running correctly:

5.1. Monitoring Endpoints

The application exposes the following monitoring endpoints:

  • Health check: /api/actuator/health

  • Metrics: /api/actuator/metrics

  • Prometheus: /api/actuator/prometheus

5.2. API Documentation

The application provides comprehensive API documentation:

  • Swagger UI is available at: /api/swagger-ui.html

  • OpenAPI specification is available at: /api/v3/api-docs

5.3. Logs

Check the application logs for messages indicating a successful startup:

Check the console output or configured log file

More details about the project logging You can read here

← Back | Main Page