Ir para o conteúdo

Step by Step — Deploying an Experiment and Running the Simulation

This guide brings together, in a single flow, what is currently spread across docs/execution-guide.md, docs/components/01-admin-api-monitor-web.md, docs/components/14-iot-replay-simulator.md, and docs/components/15-experiment-packaging.md.

The goal is to answer two operational questions:

  1. how to deploy an experiment to the web monitor;
  2. how to run the simulation by round or via MQTT replay.

When to use this guide

Use this document when you want to:

  • package and upload an experiment to the monitor;
  • start the web monitor and register the experiment;
  • run the round-based simulation in the browser;
  • replay data over MQTT to feed the DataComponent.

Prerequisites

Item Minimum Note
Java 25 Required by the current root Maven reactor
Maven 3.8+ Required to build and package
MQTT Broker reachable at MQTT_BROKER_URL Docker Compose uses TLS/mTLS on port 8883; configure TLS material before connecting.
lsof any Used by the monitor to release port 8088

Quick check:

java -version
mvn -version
echo "${MQTT_BROKER_URL:-tcp://localhost:1883}"

Flow overview

1. Prepare the experiment
2. Build the project
3. Package the experiment (when applicable)
4. Start the web monitor
5. Deploy the experiment to the monitor
6. Run the simulation
7. Check artifacts, rounds, and MQTT traffic

1. Preparing the experiment

1.1 Experiment already built into the monitor

The default experiments already registered in the monitor's bootstrap are:

  • exp-dt-federated-001
  • exp-har-smartphones-001
  • exp-ecg5000-anomaly-001

If you are just going to simulate an experiment that already exists, you can go directly to section 3. Starting the web monitor.

1.2 Experiment for dynamic deployment

To deploy a new experiment via upload, it must follow the ExperimentPackage v1 format.

In practice, the experiment needs:

  • research/experiments/{experimentId}/pom.xml
  • artifactId matching the experimentId
  • a {Algo}SessionFactory implements ExperimentSessionFactory class
  • registration in the ../scripts/package-experiment.sh script

The packaging script currently supports ECG5000, MIMIC v3.1, MNIST, and ergonomic-risk packages. Any other experimentId must be registered in scripts/package-experiment.sh with its session factory and contract version.


2. Building the project

Before packaging, deploying, or simulating:

sh scripts/compile.sh

This prepares target/classes and target/lib, which are used by the run-* scripts.


3. Starting the web monitor

3.1 Default mode

sh scripts/run-admin-web.sh

The monitor comes up at:

http://127.0.0.1:8088

3.2 Fabric ledger (required)

If you want to run with Fabric integration:

source deploy/fabric/fabric-env.sh
sh scripts/run-admin-web.sh

3.3 TLS for environments with personal data

export ADMIN_TLS_KEYSTORE=deploy/tls/admin-keystore.p12
export ADMIN_TLS_PASSWORD=changeit
sh scripts/run-admin-web.sh

Operational notes:

  • the monitor's port is fixed: 8088;
  • the script automatically terminates any other process listening on that port;
  • the monitor always uses blockchain; the script tries to load deploy/fabric/fabric-env.sh if needed.

4. Deploying the experiment

There are two valid paths.

4.1 Path A — use an experiment already registered in the monitor

This is the simplest path. After starting the monitor:

  1. go to http://127.0.0.1:8088;
  2. find the experiment on the dashboard;
  3. open the details page;
  4. go to the simulation or execution tab.

This path works well for:

  • exp-dt-federated-001
  • exp-har-smartphones-001
  • exp-ecg5000-anomaly-001

4.2 Path B — dynamic deployment via upload

Use this flow when the experiment has been prepared for ExperimentPackage v1.

Step 1 — generate the package

Example with the ECG experiment:

sh scripts/package-experiment.sh exp-ecg5000-anomaly-001

Expected output:

target/packages/exp-ecg5000-anomaly-001.hdtpkg.zip

If you want to package and submit to the platform in the same command:

sh scripts/package-experiment.sh exp-ecg5000-anomaly-001 --submit

With expected clients:

sh scripts/package-experiment.sh exp-ecg5000-anomaly-001 --submit --client-ids 1,2,3

With an explicit platform URL:

sh scripts/package-experiment.sh exp-ecg5000-anomaly-001 \
  --submit \
  --platform-url http://127.0.0.1:8088

The script sends the package to POST /experiments/deploy and writes the response to:

target/packages/{experimentId}.deploy.response

Step 2 — open the deploy screen

With the monitor running, go to:

http://127.0.0.1:8088/experiments/deploy

Step 3 — submit the package

In the form:

  1. select the .hdtpkg.zip file;
  2. enter clientIds as CSV, if you want to pre-register clients;
  3. submit the form.

After a successful upload, the monitor redirects to the created experiment's page.

If you used --submit, these manual browser upload steps are no longer necessary.

Step 4 — validate the deployment

Confirm that:

  • the experiment appears on the dashboard;
  • the details page opens normally;
  • the contract version is correct;
  • the experiment is ready for execution or simulation.

Security note

The /experiments/deploy endpoint executes code from the uploaded package and has no authentication in the MVP. Use this flow only on a trusted network.


5. Running the simulation through the web monitor

This is the main flow for round-controlled simulation.

Step 1 — open the session tab

In the monitor:

  1. open the experiment;
  2. click the ▶ Session tab.

Step 2 — start the simulation session

Fill in the fields:

  • type: har or ecg
  • path: dataset path
  • maxClients: maximum number of simulated clients
  • totalRounds: total number of rounds

Example paths:

  • research/datasets/uci-har/UCI HAR Dataset
  • research/datasets/ecg5000/ECG5000

Step 3 — choose how to advance

You can:

  • click Send round to advance one round at a time;
  • click Run All Remaining Rounds to send all pending rounds.

Step 4 — follow the execution

During the simulation, watch:

  • the experiment details tab;
  • per-round metrics;
  • the Clients tab;
  • the Blockchain tab, when using the required Fabric ledger;
  • the 📡 MQTT tab, when the gateway is active.

Expected session state

The session can be in:

  • ACTIVE
  • PAUSED
  • DONE
  • ERROR

If an error occurs, the current round should not advance automatically.


6. Running the simulation via MQTT replay

This flow is useful when you want to publish observations/events over MQTT to feed the DataComponent as if they were data arriving from real devices.

HAR

sh scripts/run-iot-simulator.sh har

With a local dataset and a client limit:

sh scripts/run-iot-simulator.sh har "research/datasets/uci-har/UCI HAR Dataset" 5

ECG5000

sh scripts/run-iot-simulator.sh ecg

With a local dataset and a client limit:

sh scripts/run-iot-simulator.sh ecg "research/datasets/ecg5000/ECG5000" 3

What happens in this mode

The simulator:

  • publishes per-client MQTT observations;
  • uses the broker configured in MQTT_BROKER_URL;
  • lets the receiving side materialize data into data/{client_id}/{experiment_id}.

7. Complete example

Example: deploy the ECG package and then run the round-based simulation in the monitor.

Terminal 1 — package

sh scripts/package-experiment.sh exp-ecg5000-anomaly-001

Terminal 2 — start the monitor

sh scripts/run-admin-web.sh

Browser

  1. go to http://127.0.0.1:8088/experiments/deploy;
  2. upload target/packages/exp-ecg5000-anomaly-001.hdtpkg.zip;
  3. open the deployed experiment;
  4. go to ▶ Session;
  5. enter:
  6. type=ecg
  7. path=research/datasets/ecg5000/ECG5000
  8. maxClients=5
  9. totalRounds=3
  10. click Start session;
  11. click Send round or Run All Remaining Rounds.

8. What to check after the simulation

Confirm the following success signals:

  • the experiment appears in the monitor;
  • the session goes from ACTIVE to DONE at the end;
  • rounds are visible on the experiment screen;
  • artifacts are generated under target/artifacts/;
  • per-client data appears under data/{client_id}/{experiment_id}/;
  • the 📡 MQTT tab shows traffic when the MQTT gateway is enabled.

Typical outputs:

data/{client_id}/{experiment_id}/dataset.csv
target/artifacts/{experiment_id}/{client_id}/round-{r}/local_update.bin
target/artifacts/{experiment_id}/{client_id}/round-{r}/metrics.json
target/artifacts/{experiment_id}/round-{r}/aggregation_report.json
target/artifacts/{experiment_id}/models/v{n}/model.bin

9. Common problems

Packaging fails saying the experiment has not been migrated

Probable cause:

  • the experimentId is not yet registered in scripts/package-experiment.sh.

The monitor comes up, but there is no MQTT traffic

Check:

  • whether the broker is active;
  • whether MQTT_BROKER_URL points to the correct broker;
  • whether the experiment/simulator actually published messages.

The simulation goes into ERROR

Check:

  • the dataset path;
  • the adapter type (har or ecg);
  • the number of clients;
  • MQTT broker availability;
  • the monitor's logs.

The experiment was deployed, but does not appear correctly

Check:

  • whether the upload was a valid .hdtpkg.zip;
  • whether the package's sessionFactoryClass is loadable;
  • whether the package passed SHA256SUMS validation.

10. Project references