Application Setup and Database Configuration

1. Overview

This guide is intended for testers/support to run the application from the dist folder. You need to:

  • Set valid java installation folder (JAVA_HOME) in app.env

  • Set the path to the dist folder (APP_HOME) in app.env.

  • Configure ACS WebService parameters.

  • Configure database connection (MySQL or Oracle).

  • Start the application using start.sh or start.cmd.

2. Required Directory Structure

The dist folder should follow this baseline structure (with common environment-dependent config files present as needed):

📁 dist/
├── 📁 bin/
│    ├── 📄 app.env           # Main configuration file
│    ├── 📄 start.cmd/sh      # Startup script
├── 📁 conf/
│    ├── 📄 hazelcast-client.xml
│    ├── 📄 ftacs.keystore        # Backend keystore used when HTTPS is enabled
│    ├── 📄 logback-spring.xml    # Default external logging configuration
│    ├── 📄 interfaceItems.json   # Interface seed data, loaded if present
│    ├── 📁 customization/
│    │    ├── 📁 def/
│    │    ├── 📁 mc/
│    │    └── 📁 sc/

3. app.env Configuration

3.1. Base directories

APP_HOME=/path/to/your/dist
JAVA_HOME=/path/to/java

3.2. ACS WebService

ACS_WEB_SERVICE_SCHEME=http
ACS_WEB_SERVICE_HOST=localhost
ACS_WEB_SERVICE_PORT=8080
ACS_WEB_SERVICE_USER=friendly
ACS_WEB_SERVICE_PASSWORD=linux4israel

ACS_WEB_SERVICE_SCHEME selects how the backend connects to the ACS SOAP web service: http (default) or https. Set ACS_WEB_SERVICE_PORT to the matching FTACS port.

For https, the ACS certificate must be trusted by the JVM. Certificates signed by a public CA work out of the box. For a self-signed or private CA certificate, import it into a truststore and pass it to the JVM:

keytool -importcert -alias ftacs -file ftacs.crt -keystore acs-truststore.p12 -storetype PKCS12 -storepass changeit
JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=/opt/app/conf/acs-truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit"
A custom truststore replaces the JVM default CA list for all outgoing TLS connections (for example Keycloak or a SAML IdP). If the backend also connects to hosts with public CA certificates, start from a copy of the JDK cacerts file and import the ACS certificate into it.

3.3. Database Connection

General properties for MySQL and Oracle

DB_HOST=localhost
DB_PASSWORD=ftacs

Option A: MySQL

DB_VENDOR=mysql
SPRING_PROFILES_ACTIVE=mysql
MYSQL_PORT=3306
MYSQL_USER=ftacs
MYSQL_SCHEMA_FTACS=ftacs
MYSQL_SCHEMA_IOTW=iotw

Option B: Oracle

DB_VENDOR=oracle
SPRING_PROFILES_ACTIVE=oracle
ORACLE_HOST_FTACS=${DB_HOST}
ORACLE_HOST_IOTW=${DB_HOST}
ORACLE_PORT=1521
ORACLE_SERVICE=XEPDB1
ORACLE_USER_FTACS=ftacs
ORACLE_USER_IOTW=iotw
ORACLE_PASSWORD_FTACS=${DB_PASSWORD}
ORACLE_PASSWORD_IOTW=${DB_PASSWORD}
This page configures the application directly (the app.env for a non-Docker dist run), so it sets the app-native variables DB_VENDOR and SPRING_PROFILES_ACTIVE. In the Docker deployment you do not edit these directly: the shared .env exposes the choice once as DB_PROFILE, and the compose files map it onto both (DB_VENDOR: ${DB_PROFILE} and SPRING_PROFILES_ACTIVE: ${DB_PROFILE}). See the deployment guide for the two-layer .env model.

4. Hazelcast configuration

Set your hazelcast url and port (default port 5701) in app.env

# === Hazelcast (optional) ===
HZ_MEMBERS=127.0.0.1:5701,127.0.0.2:5701

5. Final configuration

Place your app folder to dist.

6. Startup Instructions

  1. Edit app.env with correct APP_HOME (way/to/your/dist/folder), ACS, and database settings.

  2. Run the application:

# On Unix/Mac
./start.sh

# On Windows
start.cmd