docs: run python library solely (#187)

Add a README file to illustrate how one can run python library manually without engaging with the control plane
cisco-open · Jul 15, 2022 · f913b51 · f913b51
1 parent 4dfe0f2
commit f913b51
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 34 deletions.
diff --git a/lib/python/flame/README.md b/lib/python/flame/README.md
@@ -0,0 +1,38 @@
+# A guide to run python library locally without engaging with the system components
+
+## Environment Setup
+We recommend setting up your environment with `conda`. This example is based on Ubuntu 22.04.
+```bash
+conda create -n flame python=3.9
+conda activate flame
+
+
+pip install google
+pip install tensorflow
+pip install torch
+pip install torchvision
+
+cd ..
+make install
+```
+
+## Configuring Brokers
+As the flame system uses MQTT brokers to exchange messages during federated learning, to run the python library locally, you could either 1) install a local MQTT broker 2) use a public MQTT broker. Here we'll illustrate the second option.
+
+Go to any examples that you wish to run locally in `examples` directory, change the `host` from `"flame-mosquitto"` to `broker.hivemq.com` in the `config.json` files of both the trainer and aggregator.
+
+## Running the Python Code
+
+```bash
+cd examples/mnist/trainer
+
+python keras/main.py config.json
+```
+
+```bash
+# Open another terminal
+conda activate flame
+cd examples/mnist/aggregator
+
+python keras/main.py config.json
+```
diff --git a/lib/python/flame/examples/mnist/aggregator/config.json b/lib/python/flame/examples/mnist/aggregator/config.json
@@ -3,7 +3,7 @@
     "backend": "mqtt",
     "brokers": [
         {
-            "host": "flame-mosquitto",
+            "host": "broker.hivemq.com",
             "sort": "mqtt"
         }
     ],
@@ -37,31 +37,26 @@
         "rounds": 5
     },
     "baseModel": {
-	"name": "",
-	"version": 2
+	    "name": "",
+	    "version": 2
     },
     "job" : {
-	"id": "622a358619ab59012eabeefb",
-	"name": "mnist"
+	    "id": "622a358619ab59012eabeefb",
+	    "name": "mnist"
     },
     "registry": {
-	"sort": "mlflow",
-	"uri": "http://flame-mlflow:5000"
+	    "sort": "dummy",
+	    "uri": ""
     },
     "selector": {
-	"sort": "random",
-	"kwargs": {"k": 1}
+	    "sort": "default",
+	    "kwargs": {}
     },
     "optimizer": {
-    "sort": "fedyogi",
-    "kwargs": {
-        "beta_1": 0.9,
-        "beta_2": 0.99,
-        "eta": 1,
-        "tau": 1
-    }
+        "sort": "fedavg",
+        "kwargs": {}
     },
     "maxRunTime": 300,
-    "realm": "",
+    "realm": "default",
     "role": "aggregator"
 }
diff --git a/lib/python/flame/examples/mnist/trainer/config.json b/lib/python/flame/examples/mnist/trainer/config.json
@@ -3,7 +3,7 @@
     "backend": "mqtt",
     "brokers": [
         {
-            "host": "flame-mosquitto",
+            "host": "broker.hivemq.com",
             "sort": "mqtt"
         }
     ],
@@ -37,31 +37,26 @@
         "rounds": 5
     },
     "baseModel": {
-	"name": "",
-	"version": 1
+	    "name": "",
+	    "version": 1
     },
     "job" : {
-	"id": "622a358619ab59012eabeefb",
-	"name": "mnist"
+	    "id": "622a358619ab59012eabeefb",
+	    "name": "mnist"
     },
     "registry": {
-	"sort": "mlflow",
-	"uri": "http://flame-mlflow:5000"
+	    "sort": "dummy",
+	    "uri": ""
     },
     "selector": {
-	"sort": "random",
-	"kwargs": {"k": 1}
+	    "sort": "default",
+	    "kwargs": {}
     },
     "optimizer": {
-    "sort": "fedyogi",
-    "kwargs": {
-        "beta_1": 0.9,
-        "beta_2": 0.99,
-        "eta": 1,
-        "tau": 1
-    }
+        "sort": "fedavg",
+        "kwargs": {}
     },
     "maxRunTime": 300,
-    "realm": "us|west",
+    "realm": "default/us/west",
     "role": "trainer"
 }