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. ClickHouse 26.2 is the supported version by product decision; the relational database minimum has to be confirmed with FT DevOps before it is written down here.

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.

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, CLICKHOUSE_HOST and HZ_MEMBERS to the container names in that case.

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:

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 the two service files — ft-qoe-web/.env and ft-qoe-web/config/hazelcast-client.yaml — are published on FT_DISK (see Deployment Artifacts (FT_DISK)); 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 deliberately not created here — it is needed only when TLS is terminated in the application, and TLS Keystore (optional) creates it as its first step.

Ready-made copies of the two FT QoE Web configuration files are published on FT_DISK, under FT_DISK → RD → prerelease → ft-qoe-web. Download them from the ft-qoe-web folder on SharePoint and place each file at the path shown below.

These are the same folder and the same two 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.

Both service files are reproduced inline in this document as well (see the Reference contents column), 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 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: TZ, SPRING_PROFILES_ACTIVE, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_DATABASE, CLICKHOUSE_USERNAME, CLICKHOUSE_PASSWORD and HZ_MEMBERS are infrastructure values and belong in the root .env; every other variable 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 keystore 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.

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

2. Put a keystore in it, named server.p12. Use your CA-issued PKCS#12 keystore in production. For a development certificate, generate one directly into that directory:

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

3. Mount the directory — add the ssl line to the volumes: list of the ft-qoe-web service in compose.yml (Docker Compose), next to the config and logs mounts:

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:

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/.

The path in SSL_KEY_STORE is the container path — /etc/app/ssl/server.p12 is where step 3 mounts the host file /usr/local/ft-system/ft-qoe-web/ssl/server.p12. If the mount is missing, the container starts pointing at a file that does 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.

For the standalone docker run form in Docker Compose, the equivalent of step 3 is one more -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.

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 Hazelcast members overridden from env HZ_MEMBERS: …​ to confirm the client picked up the real cluster address rather than the bundled 127.0.0.1:5701 default.

Check application health:

The login screen is the check that does not depend on the actuator being present (see the note under HTTP Endpoints) — 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 log shows Unable to connect to any address in the config, or the application appears to run but caching silently has no effect (it is reaching 127.0.0.1:5701 inside its own container instead of the real cluster).

Fix:

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: