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

The deployment files for this service are compose.yml, the shared stack .env, and the per-service ft-device-network/.env, all reproduced in Docker Compose and Environment Configuration. There is no separate pre-configured configuration package 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 repository’s own compose.yml sets neither container_name nor a named network, so the compose file in Docker Compose adds both — an explicit container_name: ft-device-network-service and an ft-network bridge — to make that hostname stable. Any service that must resolve it has to join the same network.

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 up -d ft-device-network-service.

This follows the platform layout documented in Full System Deployment: one directory per service directly under /usr/local/ft-system, whose compose mount for this service is ./ft-device-network/logs:/app/logs.

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.

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.

container_name and the ft-network bridge are set explicitly on top of what the repository’s own compose.yml defines — see Docker Networking for why they matter.

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 cannot write to /app/logs.

Fix:

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.