Installation & Deployment

These services must be installed, running, and reachable from this host before the Service API starts. None of them are deployed by this guide.

The Hazelcast dependency is a functional dependency, not an optional cache. The bundled hazelcast-client.yaml uses connection-strategy.async-start: true / reconnect-mode: ASYNC, so the client does not block startup: the container starts and connects in the background. Until a cluster is reachable, cache-backed operations fail, so provide a reachable cluster before serving traffic. (Whether the hazelcastCacheFactory bean itself fails fast depends on its implementation in the external api-common library — verify against a real startup log if strict fail-fast behavior matters.)

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

Access to the FT_DISK — Service-API folder for the deployment files (compose.yml, the shared .env and the per-service service-api/.env) and the pre-configured service-api configuration package (service-api.yml, hazelcast-client.yaml).

When the database, Hazelcast cluster, or Northbound API runs on the host machine rather than in Docker, use one of the following as the hostname in MYSQL_HOST / ORACLE_HOST, NORTHBOUND_API_URL, and in hazelcast-client.yaml:

localhost or 127.0.0.1 will not work — inside the container these point to the container itself, not the host.

When a peer runs as a container on the same Compose network, use its container name instead (for example http://northbound-api:8080/iot-webservice).

When the Service API 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.

The application configuration files live in the config/ subdirectory, which the container mounts read-only at /etc/app. compose.yml and both .env files stay on disk but are never mounted — they are loaded via env_file.

The stack uses a two-layer environment file architecture — there is no per-vendor environment file.

Edit both layers:

MySQL is the default. Switching to Oracle is not a file swap: change DB_PROFILE, SPRING_PROFILES_ACTIVE, DB_HOST, DB_PORT and the other variables listed in Switching to Oracle inside the single root .env.

Host names for peers that run outside Docker are covered in Docker Networking.

Every variable the container reads, with the default that applies when the variable is not set. The table below lists them by the name the application reads. The MYSQL_* / ORACLE_* / DB_HOST names are supplied by the x-db-env mapping in compose.yml from the root .env — you set DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_SERVICE, DB_PROFILE and SPRING_PROFILES_ACTIVE there, not the vendor-specific names. Everything else in the table (PORT, HTTPS_PORT, the SERVER_SSL_* group, the HikariCP group, TIMEOUT, LOGGING_LEVEL_COM_FRIENDLY_APISERVICE, CONFIG_PATH, CACHE_CONFIG_PATH) belongs in service-api/.env; TZ and NORTHBOUND_API_URL are shared and stay in the root .env. Defaults come from src/main/resources/application.yml, application-mysql.yml, application-oracle.yml, logback-spring.xml and config/HttpsConfiguration.java in this repository; Required means the service cannot serve traffic correctly on a real deployment without it.

The two environment files below set the same variables; the table is the reference, the files are the starting point to edit.

hazelcast-client.yaml ships with development defaults (cluster-name: dev, cluster-members: [127.0.0.1:5701]); point it at the real cluster before starting:

For the full reference of service-api.yml and every environment variable, see Service API Configuration Guide.

The Service API serves HTTPS from a single PKCS12 keystore, keystore.p12, placed in config/ alongside the other configuration files, so it is mounted at /etc/app/keystore.p12.

For local development, generate a self-signed keystore:

The keystore must end up in /usr/local/ft-system/service-api/config/keystore.p12 — that directory is mounted read-only at /etc/app, so the file appears as /etc/app/keystore.p12. Confirm it before continuing:

Then set these values in service-api/.env: SERVER_SSL_ENABLED=true, HTTPS_PORT=8443, SERVER_SSL_KEY_STORE=file:/etc/app/keystore.p12, SERVER_SSL_KEY_STORE_PASSWORD=<keystore-password>, SERVER_SSL_KEY_PASSWORD=<key-password>.

Finally uncomment the ${SERVICE_API_HTTPS_PORT:-9445}:8443 line in the ports: mapping of compose.yml and recreate the container — the HTTPS port is not published by default.

For production, use a certificate issued by your CA/security team and export it to PKCS12 format (.p12).

The Service API has no depends_on on its infrastructure — the ACS database, Hazelcast, and Northbound API live outside this stack, so Compose cannot gate on their health. All of them should be reachable before the Service API serves traffic. The Hazelcast client connects during context initialisation; with the bundled async-start: true config it connects asynchronously and does not block startup, but operations that use the cache fail until the cluster is up (see Required External Dependencies).

Wait for each of them explicitly before starting the service:

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

This follows the source repository’s docker/compose.yml, with three deliberate differences: the configuration mount is narrowed to the config/ layout used above (the repository file mounts the whole service directory), the env_file list is replaced by the two-layer .env + service-api/.env model the platform uses, and the published HTTP port is the platform-assigned 8085, not the 8080 in the repository file — on a /usr/local/ft-system host, 8080 is already published by FTACS. To pin a specific release instead of latest, change the image: tag. The database vendor is not selected here — it is selected by DB_PROFILE / SPRING_PROFILES_ACTIVE / DB_HOST in the root .env, see Switching to Oracle.

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

A successful startup ends with the StartupInfoLogger summary banner (timestamp, PID, version, build, and Java runtime vary; the active profile reflects your deployment):

The Actuator health endpoint runs with show-details: always, so the db component reports the JDBC connection state:

If the component is missing or DOWN, check reachability from inside the container and the credentials in the root .env:

Ports the Service API dials on the existing infrastructure — confirm them against whoever operates that infrastructure, and set the matching variables in the root .env.

The application writes rolling logs to logs/application.log on the host (daily rotation, gzip-compressed, 30-day retention — see logback-spring.xml).

For servers without Harbor access, use the manual image transfer flow in Offline Servers instead of docker compose pull.

Symptom: PlaceholderResolutionException: Could not resolve placeholder 'CONFIG_PATH'

Fix:

Symptom: The container starts, but the log shows repeated Hazelcast client reconnect attempts or Unable to connect to any address in the config, and cache-backed operations fail.

Cause: The Hazelcast client cannot reach the cluster. The bundled hazelcast-client.yaml uses async-start: true / reconnect-mode: ASYNC, so the container does not exit — it starts and keeps retrying the connection in the background — but any operation that relies on the cache fails until a cluster is reachable.

Fix:

Symptom: Application logs show the configuration file is missing.

Fix:

Symptom: application.log exists in the container, but logs/ on the host is empty or missing.

Fix:

Symptom: MySQL Communications link failure or Oracle ORA-12514 in logs.

Fix:

Symptom: Connection refused or timeout errors when calling Northbound API.

Fix:

Symptom: address already in use error.

Fix:

Symptom: Building the image from source (docker buildx build) fails on ./gradlew.

Fix:

Symptom: Could not read script '/run/secrets/github_user' during a from-source build.

Fix:

When raising an issue with Friendly Technologies support, attach: