Installation & Deployment

These services must be installed, running, and reachable from this host before the FT QoE Web container starts. None of them are deployed by this guide.

No database or ClickHouse server version is pinned anywhere in this repository — the reference compose in Docker Compose deploys none of them, and build.gradle only pins JDBC drivers (com.mysql:mysql-connector-j, com.oracle.database.jdbc:ojdbc11, com.clickhouse:clickhouse-jdbc), which do not establish a server minimum. The figures above are platform-wide product decisions taken from External Components: MySQL 8.4 and Oracle 21c are the highest minimums any FT service states, and ClickHouse 26.2 is the supported minimum for the platform. Provisioning below either figure is out of support even where this service happens to start.

Network access to the hub.friendly-tech.com Docker registry (or offline image archives — see Offline Servers).

Access to the deployment files — compose.yml, the root .env, ft-qoe-web/.env and ft-qoe-web/config/hazelcast-client.yaml. FT QoE Web ships no pre-configured ft-qoe-web-conf package; the reference contents of all four files are reproduced in Preparation and Docker Compose, and the two env layers are additionally kept as templates in the repository — see FT_DISK Downloads.

The compose block in Docker Compose attaches ft-qoe-web to the ft-network bridge (driver: bridge). Peers that sit on that same bridge — a database or ClickHouse container in the same ft-system stack — are reached by container name on the container port, and that traffic never leaves the host, so it needs no firewall rule. Set DB_HOST and CLICKHOUSE_HOST to the container names in that case, and list the Hazelcast container under network.cluster-members in hazelcast-client.yaml (see Hazelcast Client Configuration).

When the infrastructure runs on another host — the topology this guide assumes — those variables hold the peer’s IP address and the published port, and every row of the table above must be open through the firewall.

If a peer runs on the same host but outside Docker, use host.docker.internal rather than localhost — inside a container localhost is the container itself:

For Hazelcast the same address goes into hazelcast-client.yaml as - host.docker.internal:5701 under network.cluster-members — FT QoE Web does not read HZ_MEMBERS.

host.docker.internal resolves to the host’s gateway address. On Docker Desktop (macOS, Windows) it works out of the box; on Linux it exists only if the container maps it, which the compose file in Docker Compose does:

The alternative is the host’s real LAN IP address.

When the FT QoE Web host cannot reach hub.friendly-tech.com, pull the image on a machine that does have registry access, export it to an archive, transfer it, and load it on the offline host.

The connected machine can run Linux, macOS, or Windows — commands are given for both shells below. It does not need to be the same platform as the offline host.

Confirm the image is present before starting, so a missing or mis-architected image fails here rather than mid-startup:

Upgrades use the same flow: pull the new tag on the connected machine, transfer and load the archive, then docker compose up -d ft-qoe-web.

Place hazelcast-client.yaml (see Hazelcast Client Configuration) in ft-qoe-web/config/ — it is mounted read-only into the container. Ready-made copies of compose.yml, ft-qoe-web/.env and ft-qoe-web/config/hazelcast-client.yaml are published on FT_DISK (see FT_DISK Downloads); apart from them FT QoE Web needs no acs_configuration.xml-style runtime configuration on disk, only the JDBC and Hazelcast connection settings supplied through environment variables. An ssl/ directory is not part of this mkdir — its content is needed only when TLS is terminated in the application, and TLS Certificate (optional) creates it as its first step. The compose block mounts it either way, so Docker creates it empty on first start if you never populate it. The certificate that goes into it is published on FT_DISK separately from the two configuration files, in the ssl subfolder of the same service folder.

Download the following from the ft-qoe-web folder on SharePoint (FT_DISK → RD → prerelease → ft-qoe-web); the root .env comes from the FT System MySQL Stack / FT System Oracle Stack folder or from the sample in Environment Configuration:

The folder carries no per-vendor environment file, and that is deliberate: the database vendor is selected once, in the root .env (SPRING_PROFILES_ACTIVE plus the DB_* values) — not by copying a .env.oracle over a .env. The Script for clearing QoE data from ACS up to (and including) 6.4.14 subfolder in the same FT_DISK folder is not part of a deployment — it belongs to QoE Data Cleanup.

These are the same folder and the same files the full-system deployment guide downloads for this service (Per-service configuration files), so a stack that already carries other FT services keeps a single source for its configuration files. All of them are reproduced inline in this document as well (Environment Configuration, Hazelcast Client Configuration, Docker Compose), so the deployment can be completed by hand if FT_DISK is unreachable — review the downloaded copies against those sections and adjust hosts, ports and credentials to the target environment before starting the stack.

The same two env layers are also kept in the repository as templates, so a change to the service and a change to its configuration travel together:

FT_DISK stays the canonical copy for a deployment; the templates carry no host-specific values and exist so the variable set can be reviewed against build.gradle, application*.yml and the Dockerfile in the same commit that changes them. The repository also holds a docker-compose.yaml at its root — that one is a developer stack (locally built Hazelcast and config server, debug port 5005) and is not the deployment compose described in Docker Compose.

The stack uses a two-layer environment file architecture — the same one the full-system deployment uses. There is no env file per database vendor: both layers are loaded together by the env_file: list in Docker Compose, in this order.

Selecting Oracle instead of MySQL is not a file swap — it is a change of SPRING_PROFILES_ACTIVE, DB_HOST, DB_PORT (and the other variables listed in the portal’s table) inside the single root .env. MySQL is the default. See Switching to Oracle for the full list.

Create ft-qoe-web/.env with the per-service variables below. The compose block in Docker Compose also writes out the *_DB_URL / CLICKHOUSE_DB_URL values in full, derived from the root .env through Compose variable interpolation — an explicit, readable form of the same fallback chain described above, not a requirement.

The variables the container actually reads, with the defaults that apply when they are left unset. Which layer each one belongs to follows two rules. First, infrastructure values shared by every service on the host — TZ, SPRING_PROFILES_ACTIVE, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, CLICKHOUSE_HOST, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_DATABASE, CLICKHOUSE_USERNAME and CLICKHOUSE_PASSWORD — belong in the root .env. Second, any variable the compose file references as ${VAR} must also be in the root .env, whatever it configures: Compose interpolates only from the shell environment and from the .env file sitting next to compose.yml, and never from a file listed under env_file: (see [env-file-is-not-interpolated]). That second rule covers QOE_WEB_PORT and QOE_WEB_JAVA_RAM. Everything else in the table below is FT QoE Web’s own and belongs in ft-qoe-web/.env. The *_DB_URL overrides may sit in either layer — keeping them out of both, and letting the root .env values drive the connection, is the simpler setup (see Wrong Database Targeted Despite Correct DB_HOST). Defaults are taken from src/main/resources/application.yml, application-mysql.yml, logback-spring.xml and the Dockerfile ENV block in this repo; Required = Yes means the container cannot reach its infrastructure without it (directly, or through the matching *_DB_URL).

HTTPS is disabled by default (SSL_ENABLED=false) — the application listens as plain HTTP on HTTPS_PORT, and TLS is expected to be terminated by a reverse proxy or ingress in front of it.

To terminate TLS in the application itself, work through the four steps below in order — the certificate has to exist on the host, be mounted into the container, and be named by the environment before SSL_ENABLED=true has any chance of working.

The certificate can be supplied in either of two forms, and the choice changes only steps 2 and 4:

Nothing has to be configured to choose between them: Spring Boot looks for the PEM properties first and falls back to the keystore only when they are absent (WebServerSslBundle.createKeyStore).

1. Create the certificate directory — the mkdir in Directory Structure creates only config and logs:

2. Put the certificate in it.

Option A — PEM pair (preferred). Download friendly.crt and friendly.key from FT_DISK, under FT_DISK → RD → prerelease → ft-qoe-web → ssl:

ft-qoe-web/ssl folder on SharePoint

Place both files, side by side, in the directory from step 1:

That pair is the Friendly Tech wildcard certificate, issued by the internal Friendly Tech Root CA and shared with the other FT services — FT UI Backend mounts the same two files at ui-backend/config/ssl/. Two properties of it are worth knowing before the first browser reaches the UI:

Option B — PKCS#12 keystore. Name it server.p12 and put it in the same directory. Use your CA-issued keystore in production. For a development certificate, generate one directly into that directory:

The config/keystore.p12 inside the image (classpath default) is a self-signed certificate intended only for local development — it is what the application falls back to when neither form is configured, and it must not be used in production.

3. Check that the directory is mounted. The compose block in Docker Compose already carries the ssl line, so on a stack built from this guide there is nothing to do here. A compose.yml that predates it needs the line added to the volumes: list of the ft-qoe-web service, next to the config and logs mounts. This step is the same for both options:

4. Set the variables in ft-qoe-web/.env (SSL_ENABLED is already there, set to false) and recreate the container with docker compose up -d ft-qoe-web.

Option A — PEM pair:

SSL_KEY_STORE and SSL_KEY_STORE_TYPE are not read in this mode; leaving them set does no harm, they are simply never reached. SSL_KEY_ALIAS still applies — it names the key entry inside the in-memory keystore — but its default (ft-qoe-web) works, so leave it alone.

Neither PEM property has an SSL_* short alias: application.yml declares placeholders for the six keystore variables only (Two naming forms for the TLS variables), so the canonical SERVER_SSL_* names are the only way to set them.

Option B — PKCS#12 keystore:

Those three cover the common case: a PKCS#12 keystore holding one key entry, whose private key is protected by the keystore password. The remaining knobs default to values that match the keystore produced by step 2 and only need setting when your keystore differs:

A wrong alias is the most common failure here: the container starts, then Tomcat aborts with java.io.IOException: Alias name [ft-qoe-web] does not identify a key entry. List what the keystore actually contains with keytool -list -keystore /usr/local/ft-system/ft-qoe-web/ssl/server.p12 -storetype PKCS12.

For mutual TLS — verifying client certificates — add a trust store as well. These properties have no SSL_* alias either, so use the Spring Boot names (Two naming forms for the TLS variables), and remember that a trust store without SERVER_SSL_CLIENT_AUTH has no effect:

Mount the trust store the same way as the keystore — step 3’s ssl mount already covers it if you put truststore.p12 in /usr/local/ft-system/ft-qoe-web/ssl/.

Every path in these variables is a container path — /etc/app/ssl/ is where step 3 mounts the host directory /usr/local/ft-system/ft-qoe-web/ssl/, so file:/etc/app/ssl/friendly.crt resolves to the host file /usr/local/ft-system/ft-qoe-web/ssl/friendly.crt. If the mount is missing, the container starts pointing at files that do not exist inside it.

Leave the ports as this guide sets them (HTTPS_PORT=8080, HTTP_PORT=8081). Enabling TLS does not move the primary connector: HTTPS_PORT is server.port in both modes, so the container keeps listening on 8080 and the compose mapping 8086 → 8080 keeps working. What changes is:

Changing HTTPS_PORT here means changing the container side of the ports: mapping in compose.yml to match — otherwise Compose publishes a port nothing listens on.

The standalone docker run form in Docker Compose carries the same mount as a -v flag: -v ./ft-qoe-web/ssl:/etc/app/ssl:ro.

FT QoE Web has no depends_on on its infrastructure — the database, ClickHouse, and Hazelcast live outside this stack, so Compose cannot gate on their health. All of them must be up before FT QoE Web launches: the Hazelcast client connects during context initialisation, and the JDBC pools fail their first health probe if the database or ClickHouse are unreachable.

Wait for each of them explicitly before starting the service:

FT QoE Web itself restarts cleanly at any time once the infrastructure is up — restart: unless-stopped reconnects it after a host reboot.

The compose.yml shipped in the ft-qoe-web folder on FT_DISK:

For Oracle, set SPRING_PROFILES_ACTIVE=oracle together with the Oracle DB_HOST / DB_PORT in the root .env — there is no separate Oracle env file — and replace the MAIN_DB_URL / QUARTZ_DB_URL / UI_DB_URL values above with Oracle JDBC URLs (jdbc:oracle:thin:@//<host>:1521/<service>) if you pin them explicitly. The complete variable list is in Switching to Oracle.

Wait 30—​60 seconds after start, then check the logs:

Look for Authenticated with server [<hazelcast-host>]:5701 and Members [N] to confirm the client reached the real cluster. A container that keeps restarting with No connection found to cluster has the wrong address in hazelcast-client.yaml — see Hazelcast Cluster Issues.

Check application health — the same endpoint the container healthcheck calls:

Expect {"status":"UP"}. With SSL_ENABLED=true the published port speaks HTTPS, so use curl -sk https://localhost:8086/qoeUI/actuator/health instead.

The login screen is the second check — it should answer with a 200 or a redirect to the login page:

Open the same URL in a browser to see the login screen:

Check that the Quartz scheduler tables were auto-initialized in ftacs_quartz on first start:

If ftacs and ftacs_qoe_ui are empty, that points at the schema-creation prerequisite in Required External Dependencies, not at FT QoE Web — it never creates those tables itself.

Check ClickHouse reachability from inside the container — on the HTTP port 8123, not the native TCP port 9000. CLICKHOUSE_HOST exists only inside the container, so the expansion has to happen there: single-quote the command and run it through the container’s shell, otherwise your own shell expands the variable to nothing before docker exec starts.

Ports FT QoE Web dials on the existing infrastructure. These are the published ports of those services — confirm them against whoever operates them, and set the matching variables in .env.

Paths are relative to the host and published port, for example http://<host>:8086/qoeUI.

The application writes to ft-qoe-web/logs/ on the host (mounted at /app/logs in the container). logback-spring.xml resolves the log directory as ${LOG_DIR:-${APP_HOME}/logs}; APP_HOME comes from the Spring property app.home, which nothing in this repo sets, so it falls back to ./, and the Dockerfile WORKDIR is /app — making the effective directory /app/logs. Set LOG_DIR explicitly to write elsewhere; the image also pre-creates /var/log/app, which stays empty unless LOG_DIR points at it.

Symptom: The ft-qoe-web container exits immediately after docker compose up.

Fix:

Symptom: DB_HOST / DB_PORT / DB_USER / DB_PASSWORD in .env are correct and point at the intended database, but FT QoE Web still connects somewhere else (or with different credentials).

Cause: MAIN_DB_URL / QUARTZ_DB_URL / UI_DB_URL / CLICKHOUSE_DB_URL always win over DB_HOST and the generic MYSQL_* / CLICKHOUSE_* variables when set — see the NOTE in Environment Configuration. A leftover *_DB_URL from an earlier config (or copied from another environment) silently overrides the values you just edited in .env.

Fix: Check whether a *_DB_URL is set in ft-qoe-web/.env or the compose environment: block before assuming .env alone controls the connection:

+

+ Remove or update the stale override, or leave DB_HOST / DB_PORT / DB_USER / DB_PASSWORD as the only source of truth and drop the *_DB_URL variables entirely if you do not need a non-default schema name.

Symptom: The container restarts every few seconds — docker ps shows a container created long ago but Up only seconds, and docker inspect ft-qoe-web --format '{{.RestartCount}}' keeps growing. The database connections succeed, then each start ends a fraction of a second after Trying to connect to cluster: dev with:

With async-start: false the container stays up instead, but startup never completes and the log repeats the connection attempts.

Cause: The client cannot reach the cluster described in the mounted hazelcast-client.yaml. Most often network.cluster-members still holds the shipped hazelcast:5701 while Hazelcast runs on another server, on the assumption that HZ_MEMBERS in .env overrides it — it does not (see the IMPORTANT note in Hazelcast Client Configuration). async-start: true turns this into the immediate failure above: the KPI cache is filled during startup, before the first connection has a chance to complete.

Fix:

HZ_MEMBERS, HZ_CLUSTER_NAME, HAZELCAST_ADDRESS and HAZELCAST_CLUSTER_NAME are not read by FT QoE Web; changing them has no effect on this problem.

Symptom: QoE data queries fail; the log reports a ClickHouse connection or protocol error.

Fix:

Symptom: docker compose up fails with bind: address already in use.

Fix:

Symptom: The container cannot write to ft-qoe-web/logs.

Fix:

The image runs as a non-root user (appuser, uid 1001) — if the host directory is owned by a different uid, the container cannot write to it even with 755 permissions; chown the directory to uid 1001 instead if $(whoami) on the host does not resolve to that uid inside the container’s namespace.

Symptom: java.lang.OutOfMemoryError in the logs, or the container is killed by the OOM killer.

Fix:

If the issue persists, collect the following and contact Friendly Tech support: