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:
- how to deploy an experiment to the web monitor;
- 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:
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-001exp-har-smartphones-001exp-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.xmlartifactIdmatching theexperimentId- a
{Algo}SessionFactory implements ExperimentSessionFactoryclass - registration in the
../scripts/package-experiment.shscript
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:
This prepares target/classes and target/lib, which are used by the run-* scripts.
3. Starting the web monitor¶
3.1 Default mode¶
The monitor comes up at:
3.2 Fabric ledger (required)¶
If you want to run with Fabric integration:
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 loaddeploy/fabric/fabric-env.shif 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:
- go to
http://127.0.0.1:8088; - find the experiment on the dashboard;
- open the details page;
- go to the simulation or execution tab.
This path works well for:
exp-dt-federated-001exp-har-smartphones-001exp-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:
Expected output:
If you want to package and submit to the platform in the same command:
With expected clients:
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:
Step 2 — open the deploy screen¶
With the monitor running, go to:
Step 3 — submit the package¶
In the form:
- select the
.hdtpkg.zipfile; - enter
clientIdsas CSV, if you want to pre-register clients; - 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:
- open the experiment;
- click the
▶ Sessiontab.
Step 2 — start the simulation session¶
Fill in the fields:
type:harorecgpath: dataset pathmaxClients: maximum number of simulated clientstotalRounds: total number of rounds
Example paths:
research/datasets/uci-har/UCI HAR Datasetresearch/datasets/ecg5000/ECG5000
Step 3 — choose how to advance¶
You can:
- click
Send roundto advance one round at a time; - click
Run All Remaining Roundsto send all pending rounds.
Step 4 — follow the execution¶
During the simulation, watch:
- the experiment details tab;
- per-round metrics;
- the
Clientstab; - the
Blockchaintab, when using the required Fabric ledger; - the
📡 MQTTtab, when the gateway is active.
Expected session state¶
The session can be in:
ACTIVEPAUSEDDONEERROR
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¶
With a local dataset and a client limit:
ECG5000¶
With a local dataset and a client limit:
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¶
Terminal 2 — start the monitor¶
Browser¶
- go to
http://127.0.0.1:8088/experiments/deploy; - upload
target/packages/exp-ecg5000-anomaly-001.hdtpkg.zip; - open the deployed experiment;
- go to
▶ Session; - enter:
type=ecgpath=research/datasets/ecg5000/ECG5000maxClients=5totalRounds=3- click
Start session; - click
Send roundorRun 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
ACTIVEtoDONEat 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
📡 MQTTtab 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
experimentIdis not yet registered inscripts/package-experiment.sh.
The monitor comes up, but there is no MQTT traffic¶
Check:
- whether the broker is active;
- whether
MQTT_BROKER_URLpoints to the correct broker; - whether the experiment/simulator actually published messages.
The simulation goes into ERROR¶
Check:
- the dataset path;
- the adapter type (
harorecg); - 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
sessionFactoryClassis loadable; - whether the package passed
SHA256SUMSvalidation.