All-in-One UI Services Deployment

Overview

This deployment runs all UI services on a single host using Docker Compose:

UI Backend (Spring Boot)
UI Portals (Angular on Nginx)
FT Device Network Service (Spring Boot)
AI Agent Service (Python)
PostgreSQL database (for AI Agent)

Architecture

Prerequisites

Required External Components

The following components must be installed and accessible before deployment:

Component	Purpose	Default Port
MySQL or Oracle	Main application database	3306 (MySQL) / 1521 (Oracle)
Hazelcast	Distributed cache	5701
FTACS Application	ACS web service	8080
Clickhouse	Analytics database	9000

Component

Purpose

Default Port

MySQL or Oracle

Main application database

3306 (MySQL) / 1521 (Oracle)

Hazelcast

Distributed cache

5701

FTACS Application

ACS web service

8080

Clickhouse

Analytics database

9000

System Requirements

Docker Engine 20.10+
Docker Compose 2.0+
Minimum 4GB RAM
20GB free disk space

Deployment Steps

1. Prepare Environment File

Choose the appropriate environment file based on your database:

MySQL

cp .env.mysql .env

Oracle

cp .env.oracle .env

2. Configure Host Variables

Edit .env and replace placeholder values with actual hostnames or IP addresses:

# Required replacements:
~HOST~            → Your server hostname/IP (e.g., 192.168.1.100)
~HAZEL_HOST~      → Hazelcast server (e.g., 192.168.1.50)
~FTACS_HOST~      → FTACS server (e.g., 192.168.1.60)
~CLICKHOUSE_HOST~ → Clickhouse server (e.g., 192.168.1.70)
~MYSQL_HOST~      → MySQL server (for MySQL deployment)
~ORACLE_HOST~     → Oracle server (for Oracle deployment)

Example:

FT_UI_HOST=192.168.1.100
HZ_MEMBERS=192.168.1.50:5701,192.168.1.51:5701,192.168.1.52:5701
ACS_WEB_SERVICE_HOST=192.168.1.60
CLICKHOUSE_HOST=192.168.1.70
DB_HOST=192.168.1.80

3. Create Data Directories

mkdir -p /usr/local/ft-services/{ui-backend-conf,ft-data/{ui-portals/{backend,nginx}/logs,ft-device-network/logs,ai-agent/postgres/data}}

ui-backend-conf requires predefined application configuration files. See separate-host deployment documentation for detailed configuration instructions.

4. Deploy Services

docker compose up -d

5. Verify Deployment

Check service health:

docker compose ps

All services should show status as healthy or running.

Environment Variables

Common Variables

Variable Description Default Required

Variable	Description	Default	Required
`DATA_FOLDER`	Base directory for persistent data and configurations	`/usr/local/ft-services`	Yes
`TZ`	Timezone for all services	`Europe/Kiev`	Yes
`DB_VENDOR`	Database type: `mysql` or `oracle`	`mysql`	Yes
`DB_PASSWORD`	Database password	`ftacs`	Yes

DATA_FOLDER

Base directory for persistent data and configurations

/usr/local/ft-services

Yes

TZ

Timezone for all services

Europe/Kiev

Yes

DB_VENDOR

Database type: mysql or oracle

mysql

Yes

DB_PASSWORD

Database password

ftacs

Yes

Database Configuration

MySQL

Variable Description Default

Variable	Description	Default
`DB_HOST`	MySQL server address	-
`MYSQL_PORT`	MySQL port	`3306`
`MYSQL_USER`	MySQL username	`ftacs`

DB_HOST

MySQL server address

MYSQL_PORT

MySQL port

3306

MYSQL_USER

MySQL username

ftacs

Oracle

Variable Description Default

Variable	Description	Default
`DB_HOST`	Oracle server address	-
`ORACLE_PORT`	Oracle port	`1521`
`ORACLE_SERVICE`	Oracle service name	`XEPDB1`
`ORACLE_USER_FTACS`	Oracle username	`ftacs`

DB_HOST

Oracle server address

ORACLE_PORT

Oracle port

1521

ORACLE_SERVICE

Oracle service name

XEPDB1

ORACLE_USER_FTACS

Oracle username

ftacs

External Dependencies

Variable Description Default Required

Variable	Description	Default	Required
`HZ_MEMBERS`	Hazelcast cluster members (comma-separated list of HOST:PORT)	`_{HAZEL_HOST}:5701`	Yes
`ACS_WEB_SERVICE_HOST`	FTACS application host	`_{FTACS_HOST}`	Yes
`ACS_WEB_SERVICE_PORT`	FTACS application port	`8080`	Yes
`CLICKHOUSE_HOST`	Clickhouse server address	`_{CLICKHOUSE_HOST}`	Yes
`CLICKHOUSE_PORT`	Clickhouse port	`9000`	Yes
`CLICKHOUSE_DATABASE`	Clickhouse database name	`ftacs_qoe_ui_data`	Yes
`CLICKHOUSE_USERNAME`	Clickhouse username	`ftacs`	Yes
`CLICKHOUSE_PASSWORD`	Clickhouse password	`ftacs`	Yes

HZ_MEMBERS

Hazelcast cluster members (comma-separated list of HOST:PORT)

_{HAZEL_HOST}:5701

Yes

ACS_WEB_SERVICE_HOST

FTACS application host

_{FTACS_HOST}

Yes

ACS_WEB_SERVICE_PORT

FTACS application port

8080

Yes

CLICKHOUSE_HOST

Clickhouse server address

_{CLICKHOUSE_HOST}

Yes

CLICKHOUSE_PORT

Clickhouse port

9000

Yes

CLICKHOUSE_DATABASE

Clickhouse database name

ftacs_qoe_ui_data

Yes

CLICKHOUSE_USERNAME

Clickhouse username

ftacs

Yes

CLICKHOUSE_PASSWORD

Clickhouse password

ftacs

Yes

UI Services Configuration

Variable Description Default Required

Variable	Description	Default	Required
`HOST`	Public hostname for UI access	`_HOST`	Yes
`FT_UI_HTTP_PORT`	UI Portals HTTP port	`8880`	Yes
`FT_UI_HTTPS_PORT`	UI Portals HTTPS port	`8843`	Yes
`FT_UI_BACKEND_HTTP_PORT`	Backend API port	`8881`	Yes
`FT_GRAFANA_API_URL`	Grafana url for dashboards exporting (http://IP:PORT/)		No
`FT_UI_BACKEND_JAVA_RAM`	Backend JVM memory settings	`-Xms512m -Xmx2g`	No
`FT_UI_BACKEND_LOG_LEVEL`	Backend log level	`info`	No
`FT_UI_BACKEND_KEYWORD`	Internal authentication keyword for cross-application communication (see separate-host deployment for details)	`ft12Internal%^`	Yes

HOST

Public hostname for UI access

_HOST

Yes

FT_UI_HTTP_PORT

UI Portals HTTP port

8880

Yes

FT_UI_HTTPS_PORT

UI Portals HTTPS port

8843

Yes

FT_UI_BACKEND_HTTP_PORT

Backend API port

8881

Yes

FT_GRAFANA_API_URL

Grafana url for dashboards exporting (http://IP:PORT/)

FT_UI_BACKEND_JAVA_RAM

Backend JVM memory settings

-Xms512m -Xmx2g

FT_UI_BACKEND_LOG_LEVEL

Backend log level

info

FT_UI_BACKEND_KEYWORD

Internal authentication keyword for cross-application communication (see separate-host deployment for details)

ft12Internal%^

Yes

FT Device Network Configuration

Variable Description Default Required

Variable	Description	Default	Required
`FT_DEVICE_NETWORK_HTTP_PORT`	Service HTTP port	`8383`	Yes
`FT_DEVICE_NETWORK_JAVA_RAM`	JVM memory settings	`-Xms256m -Xmx1g`	No
`FT_DEVICE_NETWORK_LOG_LEVEL`	Log level	`info`	No

FT_DEVICE_NETWORK_HTTP_PORT

Service HTTP port

8383

Yes

FT_DEVICE_NETWORK_JAVA_RAM

JVM memory settings

-Xms256m -Xmx1g

FT_DEVICE_NETWORK_LOG_LEVEL

Log level

info

AI Agent Configuration

Variable Description Default Required

Variable	Description	Default	Required
`POSTGRES_HOST`	PostgreSQL hostname (internal)	`postgres`	Yes
`POSTGRES_PORT`	PostgreSQL port	`5432`	Yes
`POSTGRES_DB`	PostgreSQL database name	`ftl_ai`	Yes
`POSTGRES_USER`	PostgreSQL username	`postgres`	Yes
`POSTGRES_PASSWORD`	PostgreSQL password	`postgres`	Yes
`GOOGLE_API_KEY`	Google API key for AI features	-	Yes
`FTL_REQUESTS_TIMEOUT_IN_SEC`	API request timeout in seconds	`60`	No
`FTL_COMMANDS_TIMEOUT_IN_SEC`	Device command timeout in seconds	`180`	No
`TOTAL_MAX_TOKENS`	Maximum tokens for LLM	`5000`	No
`MAX_AUDIO_SIZE_IN_BYTES`	Maximum audio file size	`5242880` (5MB)	No
`DB_MIN_POOL_SIZE`	Minimum db pool size	`10`	Yes
`DB_MAX_POOL_SIZE`	Maximum db pool size	`1000`	Yes

POSTGRES_HOST

PostgreSQL hostname (internal)

postgres

Yes

POSTGRES_PORT

PostgreSQL port

5432

Yes

POSTGRES_DB

PostgreSQL database name

ftl_ai

Yes

POSTGRES_USER

PostgreSQL username

postgres

Yes

POSTGRES_PASSWORD

PostgreSQL password

postgres

Yes

GOOGLE_API_KEY

Google API key for AI features

Yes

FTL_REQUESTS_TIMEOUT_IN_SEC

API request timeout in seconds

60

FTL_COMMANDS_TIMEOUT_IN_SEC

Device command timeout in seconds

180

TOTAL_MAX_TOKENS

Maximum tokens for LLM

5000

MAX_AUDIO_SIZE_IN_BYTES

Maximum audio file size

5242880 (5MB)

DB_MIN_POOL_SIZE

Minimum db pool size

10

Yes

DB_MAX_POOL_SIZE

Maximum db pool size

1000

Yes

Service Access

After successful deployment, access services at:

Service URL Description

Service	URL	Description
UI Portals	`http://<FT_UI_HOST>:8880`	Main web interface
UI Backend API	`http://<FT_UI_HOST>:8881/iot-webservice/swagger-ui/index.html`	API documentation
FT Device Network	`http://<FT_UI_HOST>:8383/api/actuator/health`	Health check endpoint
AI Agent	`http://<FT_UI_HOST>:8882`	AI agent service

UI Portals

http://<FT_UI_HOST>:8880

Main web interface

UI Backend API

http://<FT_UI_HOST>:8881/iot-webservice/swagger-ui/index.html

API documentation

FT Device Network

http://<FT_UI_HOST>:8383/api/actuator/health

Health check endpoint

AI Agent

http://<FT_UI_HOST>:8882

AI agent service

Exposed Ports

The following ports are exposed on the host:

Port Service Protocol Configurable Via

Port	Service	Protocol	Configurable Via
8880	UI Portals (Nginx)	HTTP	`FT_UI_HTTP_PORT`
8843	UI Portals (Nginx)	HTTPS	`FT_UI_HTTPS_PORT`
8881	UI Backend (Spring Boot)	HTTP	`FT_UI_BACKEND_HTTP_PORT`
8383	FT Device Network (Spring Boot)	HTTP	`FT_DEVICE_NETWORK_HTTP_PORT`

8880

UI Portals (Nginx)

HTTP

FT_UI_HTTP_PORT

8843

UI Portals (Nginx)

HTTPS

FT_UI_HTTPS_PORT

8881

UI Backend (Spring Boot)

HTTP

FT_UI_BACKEND_HTTP_PORT

8383

FT Device Network (Spring Boot)

HTTP

FT_DEVICE_NETWORK_HTTP_PORT

To verify ports are listening:

netstat -tlnp | grep -E '8880|8881|8383|8882'
# or
ss -tlnp | grep -E '8880|8881|8383|8882'

Service Startup Order

Services start in the following order with health checks:

PostgreSQL - Database for AI Agent
UI Backend - REST API service (waits for DB)
UI Portals - Web interface (waits for backend)
FT Device Network - Device management service (independent start)
AI Agent - AI service (waits for PostgreSQL, UI Backend, and FT Device Network)

Data Persistence

Persistent data is stored in the following locations (assuming DATA_FOLDER=/usr/local/ft-services):

Service Path Content

Service	Path	Content
UI Backend Config	`${DATA_FOLDER}/ui-backend-conf`	Configuration files (must be pre-configured)
UI Backend Logs	`${DATA_FOLDER}/ft-data/ui-portals/backend/logs`	Application logs
UI Portals Logs	`${DATA_FOLDER}/ft-data/ui-portals/nginx/logs`	Nginx access and error logs
FT Device Network Logs	`${DATA_FOLDER}/ft-data/ft-device-network/logs`	Application logs
PostgreSQL Data	`${DATA_FOLDER}/ft-data/ai-agent/postgres/data`	Database files

UI Backend Config

${DATA_FOLDER}/ui-backend-conf

Configuration files (must be pre-configured)

UI Backend Logs

${DATA_FOLDER}/ft-data/ui-portals/backend/logs

Application logs

UI Portals Logs

${DATA_FOLDER}/ft-data/ui-portals/nginx/logs

Nginx access and error logs

FT Device Network Logs

${DATA_FOLDER}/ft-data/ft-device-network/logs

Application logs

PostgreSQL Data

${DATA_FOLDER}/ft-data/ai-agent/postgres/data

Database files

Folder structure:

/usr/local/ft-services/
├── ui-backend-conf/          # Configuration files
└── ft-data/                  # Runtime data and logs
    ├── ui-portals/
    │   ├── backend/logs/
    │   └── nginx/logs/
    ├── ft-device-network/logs/
    └── ai-agent/postgres/data/

Troubleshooting

Check Service Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f ui-backend
docker compose logs -f portals
docker compose logs -f ft-device-network-service
docker compose logs -f ui-ai-agent
docker compose logs -f postgres

Common Issues

Services Not Starting

Check if all external dependencies are accessible:

# Test database connection
telnet <DB_HOST> 3306    # MySQL
telnet <DB_HOST> 1521    # Oracle

# Test Hazelcast
telnet <HAZEL_HOST> 5701

# Test FTACS
curl http://<FTACS_HOST>:8080

# Test Clickhouse
telnet <CLICKHOUSE_HOST> 9000

Health Check Failing

Wait for services to fully initialize. Health checks run every 10-30 seconds:

docker compose ps

If a service remains unhealthy after 5 minutes, check its logs.

Port Already in Use

If ports are already in use, modify port mappings in .env:

FT_UI_HTTP_PORT=8880
FT_UI_HTTPS_PORT=8843
FT_UI_BACKEND_HTTP_PORT=8881
FT_DEVICE_NETWORK_HTTP_PORT=8383

Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart ui-backend

Maintenance

Update Services

Pull latest images and restart:

# Pull latest images
docker compose pull

# Restart with new images
docker compose up -d

Force Repull Images

Force Docker to pull fresh images (ignores cache):

# Stop services
docker compose down

# Remove existing images
docker compose pull --ignore-pull-failures

# Or remove images manually
docker images | grep "hub.friendly-tech.com" | awk '{print $3}' | xargs docker rmi -f

# Start with fresh images
docker compose up -d

Stop Services

# Stop services (keeps data)
docker compose down

# Stop services and remove all data (WARNING: deletes all persistent data)
docker compose down -v

# Remove specific volumes only
docker volume rm ft-ui-services_postgres_data

Backup PostgreSQL

docker compose exec postgres pg_dump -U postgres ftl_ai > backup_$(date +%Y%m%d).sql

View Resource Usage

docker stats