Installation & Deployment

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

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

Access to the FT_DISK folders listed in Download Deployment Files for the deployment files — the dedicated compose.ft-device-network.yaml, the shared .env, and the per-service ft-device-network/.env. Beyond them there is nothing to download: the only volume the container mounts is its logs/ directory, and the Hazelcast client configuration is bundled inside the image rather than mounted from disk.

Other services on the same Docker network reach this one by the container hostname ft-device-network-service; the UI Backend depends on exactly that resolution (see Overview). The compose file in Docker Compose — and the one shipped in the repository, which matches it — sets both an explicit container_name: ft-device-network-service and the shared external network ft-network, to make that hostname stable. Any service that must resolve it has to join the same network. It has to be external: true and created once per host with docker network create ft-network: declared as a plain driver: bridge it would become the project-scoped ft-device-network_ft-network, which callers in other Compose projects cannot reach.

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 target 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 -f compose.ft-device-network.yaml up -d ft-device-network-service.

This follows the platform layout documented in Full System Deployment: the shared platform root is /usr/local/ft-system, with this service’s ft-device-network/ runtime directory below it. The Compose mount for this service is ${DATA_FOLDER:-.}/ft-device-network/logs:/app/logs, which resolves to /usr/local/ft-system/ft-device-network/logs with the DATA_FOLDER value from the shared .env.

Environment configuration is split into two layers, exactly as in Full System Deployment:

Both files are listed in this service’s env_file (see Docker Compose); values in the per-service file are applied last and win on a name collision.

Shipped templates: FT_DISK — ONE_IOT_UI/docker for the shared layer and FT_DISK — ONE_IOT_UI/docker/ft-device-network for the per-service layer (see Download Deployment Files). Replace the placeholders in the copies on the host.

This service has no depends_on on its infrastructure — ClickHouse, Hazelcast, and FTACS live outside this stack, so Compose cannot gate on their health. ClickHouse and Hazelcast must both be reachable before the container starts, since Flyway migrates the schema and the Hazelcast client connects synchronously during startup; either one being unreachable fails the container. FTACS does not block startup, but no device data flows in until it is healthy — see Required External Dependencies.

The container itself restarts cleanly at any time once ClickHouse and Hazelcast are up — restart: unless-stopped reconnects it after a host reboot.

compose.ft-device-network.yaml is the dedicated Compose file from FT_DISK (see Download Deployment Files). Run it from /usr/local/ft-system with docker compose -f compose.ft-device-network.yaml. It sets no JAVA_OPTS under environment: — the JVM options come from ft-device-network/.env through env_file: — and applies no database block, because this service reads no DB_* / MYSQL_* variables.

container_name and the external ft-network are what make the hostname ft-device-network-service resolvable from other Compose projects — see Docker Networking for why they matter. The repository’s own compose.yml is identical to this file. In the full-system compose.yml of the FT System MySQL/Oracle Stack the same service differs only in topology: it adds profiles: [portals] and depends_on on ClickHouse, Hazelcast and FTACS, mounts ./ft-device-network/logs, joins the stack’s own ft-network, and has no extra_hosts.

Wait 30-40 seconds after start (the healthcheck start_period), then check the logs:

A successful startup logs Flyway applying the ClickHouse migrations from classpath:db/changelog (first start only), followed by the standard Spring Boot ready marker:

The health endpoint must return {"status":"UP"}; Swagger UI must return HTTP 200 (redirects to /api/swagger-ui/index.html).

Flyway creates the schema automatically on first start — confirm the tables exist:

Expect the nine tables network_client, network_wifi_band, network_external_interface, network_issue, network_score, network_device_info, network_device_parameters, network_device_status, and network_interface_stats (see Database Configuration — Overview for what each stores), plus Flyway’s own flyway_schema_history.

The service terminates plain HTTP only; the image carries no TLS keystore configuration.

All paths include the /api context path.

The application writes to ft-device-network/logs/ under DATA_FOLDER:

Flyway migrates the ClickHouse schema automatically on the first start of a new version; a failed migration is logged and, per the service’s custom retry strategy, marked [SKIPPED] rather than blocking startup — see Database Configuration — Custom Migration Strategy. Verify the expected schema change actually applied after any upgrade that touches the database.

Symptom: The ft-device-network-service container exits immediately after docker compose up.

Fix:

Symptom: Startup fails with a clickhouse-jdbc connection error, or Flyway reports a failed migration.

Fix:

Symptom: The log shows Unable to connect to any address in the config, or the container exits during startup with a Hazelcast client error.

Fix:

Symptom: The service is healthy and the REST API responds, but /api/data/** returns stale or no data for devices that should be reporting. Nothing in the log flags this.

Cause: device data arrives through the Hazelcast queue networkDeviceParameterDataQueue, populated by FTACS. If FTACS is down, on a different Hazelcast cluster, or not yet processing parameters for the device, nothing arrives — and unlike ClickHouse/Hazelcast, this does not fail the container.

Fix:

Symptom: Repeated MQTT connection failures or reconnect attempts logged at startup and periodically afterward.

Cause: MQTT_URL defaults to tcp://localhost:1883, which resolves to the container itself. Unless MQTT-based ingestion is explicitly configured (see the MQTT broker row in Required External Dependencies), this is expected and does not affect the container’s health or the Hazelcast-based ingestion path.

Fix: if MQTT ingestion is intentionally unused, ignore these log lines. If it is intended to be used, verify MQTT_URL points at a reachable broker and MQTT_USERNAME/MQTT_PASSWORD are correct.

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

Fix:

Symptom: The container is killed by the OOM killer, or logs/heapdump.hprof appears.

Fix:

Symptom: The container logs Permission denied while writing /app/logs, or no application log appears in the host directory.

Cause: The image runs as 1001:0, but the bind-mounted host directory is owned by another identity, commonly root:root.

Fix:

Use the actual DATA_FOLDER prefix when it differs from /usr/local/ft-system.

Collect the following before raising a support request, so the first reply is not a request for more data:

Include the image tag in use, the serial number of an affected device, and whether ClickHouse and Hazelcast were reachable at the time. Route the request to the FT Device Network Service owner listed for your deployment.