From ea609666b32f14ea6600d3391f2da97c284b714b Mon Sep 17 00:00:00 2001 From: Rodney Osodo Date: Fri, 20 Dec 2024 14:11:34 +0300 Subject: [PATCH] docs: add getting started documentation Signed-off-by: Rodney Osodo --- docs/api/postman_collection.json | 433 +++++++++++++++++++++++++++++++ docs/getting-started.md | 279 ++++++++++++++++++++ 2 files changed, 712 insertions(+) create mode 100644 docs/api/postman_collection.json diff --git a/docs/api/postman_collection.json b/docs/api/postman_collection.json new file mode 100644 index 0000000..bbd9d1f --- /dev/null +++ b/docs/api/postman_collection.json @@ -0,0 +1,433 @@ +{ + "info": { + "_postman_id": "3ce70d97-6e67-4bc9-810f-1ea801bc55f9", + "name": "Propeller", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", + "_exporter_id": "5838754", + "_collection_link": "https://ox6flab.postman.co/workspace/Magistrala~acba89f8-0255-435e-9547-59e542474e21/collection/5838754-3ce70d97-6e67-4bc9-810f-1ea801bc55f9?action=share&source=collection_link&creator=5838754" + }, + "item": [ + { + "name": "Manager", + "item": [ + { + "name": "Proplets", + "item": [ + { + "name": "Get Proplet", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{MANAGER_BASE_URL}}/proplets/{{WORKER_ID}}", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "proplets", + "{{WORKER_ID}}" + ] + } + }, + "response": [] + }, + { + "name": "List Proplets", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{MANAGER_BASE_URL}}/proplets", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "proplets" + ], + "query": [ + { + "key": "limit", + "value": "1000", + "disabled": true + } + ] + } + }, + "response": [] + } + ] + }, + { + "name": "Task", + "item": [ + { + "name": "Create Task", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "function constructVisualizerPayload() {", + " var res = pm.response.json();", + " var id = res.id;", + " return id;", + "}", + "", + "pm.collectionVariables.set('TASK_ID', constructVisualizerPayload());", + "" + ], + "type": "text/javascript", + "packages": {} + } + }, + { + "listen": "prerequest", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"name\": \"add\",\n \"inputs\": [\n 10,\n 20\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks" + ] + } + }, + "response": [] + }, + { + "name": "Get Task", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks/{{TASK_ID}}", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks", + "{{TASK_ID}}" + ] + } + }, + "response": [] + }, + { + "name": "Update Task", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + }, + { + "listen": "prerequest", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + } + ], + "request": { + "method": "PUT", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"name\": \"add\",\n \"inputs\": [\n 10,\n 20\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks/{{TASK_ID}}", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks", + "{{TASK_ID}}" + ] + } + }, + "response": [] + }, + { + "name": "Upload Wasm File", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + }, + { + "listen": "prerequest", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + } + ], + "request": { + "method": "PUT", + "header": [], + "body": { + "mode": "formdata", + "formdata": [ + { + "key": "file", + "type": "file", + "src": "postman-cloud:///1efb9331-db42-42b0-818c-ea887cc3579a" + } + ] + }, + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks/{{TASK_ID}}/upload", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks", + "{{TASK_ID}}", + "upload" + ] + } + }, + "response": [] + }, + { + "name": "List Tasks", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks" + ], + "query": [ + { + "key": "limit", + "value": "1000", + "disabled": true + } + ] + } + }, + "response": [] + }, + { + "name": "Delete Task", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + }, + { + "listen": "prerequest", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + } + ], + "request": { + "method": "DELETE", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"name\": \"{{$randomCompanyName}}\"\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks/{{TASK_ID}}", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks", + "{{TASK_ID}}" + ] + } + }, + "response": [] + }, + { + "name": "Start Task", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + }, + { + "listen": "prerequest", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + } + ], + "request": { + "method": "POST", + "header": [], + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks/{{TASK_ID}}/start", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks", + "{{TASK_ID}}", + "start" + ] + } + }, + "response": [] + }, + { + "name": "Stop Task", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + }, + { + "listen": "prerequest", + "script": { + "exec": [ + "" + ], + "type": "text/javascript", + "packages": {} + } + } + ], + "request": { + "method": "POST", + "header": [], + "url": { + "raw": "{{MANAGER_BASE_URL}}/tasks/{{TASK_ID}}/stop", + "host": [ + "{{MANAGER_BASE_URL}}" + ], + "path": [ + "tasks", + "{{TASK_ID}}", + "stop" + ] + } + }, + "response": [] + } + ] + } + ] + } + ], + "event": [ + { + "listen": "prerequest", + "script": { + "type": "text/javascript", + "packages": {}, + "exec": [ + "" + ] + } + }, + { + "listen": "test", + "script": { + "type": "text/javascript", + "packages": {}, + "exec": [ + "" + ] + } + } + ], + "variable": [ + { + "key": "MANAGER_BASE_URL", + "value": "http://localhost:8080", + "type": "string" + }, + { + "key": "WORKER_ID", + "value": "" + }, + { + "key": "TASK_ID", + "value": "" + } + ] +} \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md index bad5562..9c495dd 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1 +1,280 @@ # Getting Started + +Before proceeding, install the following prerequisites: + +- [A Go compiler (Go 1.23 or later)](https://go.dev/doc/install) +- [Make](https://www.gnu.org/software/make/manual/make.html) +- [Docker](https://docs.docker.com/) +- [Wasmtime](https://wasmtime.dev/) +- [TinyGo](https://tinygo.org/getting-started/install/) +- [Magistrala CLI](https://github.com/absmach/magistrala) +- [Mosquitto](https://mosquitto.org/) + +## Start Docker composition + +Start docker composition + +```bash +cd propeller +make start-magistrala +``` + +To install the Magistrala CLI, follow the instructions [here](https://docs.magistrala.abstractmachines.fr/getting-started/#step-2-install-the-cli). + +## Provision Magistrala + +Login as admin user + +```bash +USER_TOKEN=$(magistrala-cli users token admin 12345678 | jq -r .access_token) +``` + +Create a domain + +```bash +DOMAIN_ID=$(magistrala-cli domains create demo demo $USER_TOKEN | jq -r .id) +``` + +Create a thing called manager + +```bash +magistrala-cli things create '{"name": "Propeller Manager", "tags": ["manager", "propeller"], "status": "enabled"}' $DOMAIN_ID $USER_TOKEN +``` + +This will output a response like the following + +```json +{ + "created_at": "2024-12-20T09:56:05.241227Z", + "credentials": { + "secret": "64b3742e-beee-4bd9-8673-a7b1dbfe4115" + }, + "domain_id": "c1908400-701b-4f55-82ae-45a5997b2df6", + "id": "70fc2b08-a2ce-4294-8003-aeb3df0ff505", + "name": "Propeller Manager", + "status": "enabled", + "tags": ["manager", "propeller"], + "updated_at": "0001-01-01T00:00:00Z" +} +``` + +Set the following environment variables from the respose + +```bash +export MANAGER_THING_ID="" +export MANAGER_THING_KEY="" +``` + +For example + +```bash +export MANAGER_THING_ID="70fc2b08-a2ce-4294-8003-aeb3df0ff505" +export MANAGER_THING_KEY="64b3742e-beee-4bd9-8673-a7b1dbfe4115" +``` + +Create a channel called manager + +```bash +magistrala-cli channels create '{"name": "Propeller Manager", "tags": ["manager", "propeller"], "status": "enabled"}' $DOMAIN_ID $USER_TOKEN +``` + +```json +{ + "created_at": "2024-12-20T09:57:12.510144Z", + "domain_id": "c1908400-701b-4f55-82ae-45a5997b2df6", + "id": "f8201a3c-7fd3-4468-bc85-8824ec0ab4d3", + "name": "Propeller Manager", + "status": "enabled", + "updated_at": "0001-01-01T00:00:00Z" +} +``` + +Set the following environment variables from the respose + +```bash +export MANAGER_CHANNEL_ID="" +``` + +For example + +```bash +export MANAGER_CHANNEL_ID="f8201a3c-7fd3-4468-bc85-8824ec0ab4d3" +``` + +Connect the thing to the manager channel + +```bash +magistrala-cli things connect $MANAGER_THING_ID $MANAGER_CHANNEL_ID $DOMAIN_ID $USER_TOKEN +``` + +Create a thing called proplet + +```bash +magistrala-cli things create '{"name": "Propeller Proplet", "tags": ["proplet", "propeller"], "status": "enabled"}' $DOMAIN_ID $USER_TOKEN +``` + +```json +{ + "created_at": "2024-12-20T09:58:00.282984Z", + "credentials": { + "secret": "ab8543bd-1f4b-4df1-b252-4d35c7aaffa2" + }, + "domain_id": "c1908400-701b-4f55-82ae-45a5997b2df6", + "id": "65f31506-80f1-48f4-b2d2-ff2487d4baad", + "name": "Propeller Proplet", + "status": "enabled", + "tags": ["proplet", "propeller"], + "updated_at": "0001-01-01T00:00:00Z" +} +``` + +Set the following environment variables from the respose + +```bash +export PROPLET_THING_ID="" +export PROPLET_THING_KEY="" +``` + +For example + +```bash +export PROPLET_THING_ID="65f31506-80f1-48f4-b2d2-ff2487d4baad" +export PROPLET_THING_KEY="ab8543bd-1f4b-4df1-b252-4d35c7aaffa2" +``` + +Connect the thing to the manager channel + +```bash +magistrala-cli things connect $PROPLET_THING_ID $MANAGER_CHANNEL_ID $DOMAIN_ID $USER_TOKEN +``` + +## Start the manager + +To start the manager, run the following command + +```bash +export MANAGER_THING_ID="" +export MANAGER_THING_KEY="" +export PRMANAGER_CHANNEL_ID="" +export PROPLET_THING_ID="" +export PROPLET_THING_KEY="" +propeller-manager +``` + +## Start the proplet + +To start the proplet, run the following command + +```bash +export MANAGER_THING_ID="" +export MANAGER_THING_KEY="" +export PROPLET_CHANNEL_ID="" +export PROPLET_THING_ID="" +export PROPLET_THING_KEY="" +propeller-proplet +``` + +## Postman Colletion + +This is a [collection](./api/postman_collection.json) of the API calls that can be used to interact with the Propeller system. + +## API + +### List Proplets + +```bash +curl -X GET "http://localhost:7070/proplets" +``` + +This will output a response like the following + +```json +{ + "offset": 0, + "limit": 100, + "total": 1, + "proplets": [ + { + "id": "65f31506-80f1-48f4-b2d2-ff2487d4baad", + "name": "Edouard-Harker", + "task_count": 0, + "alive": true, + "alive_history": [ + "2024-12-20T13:06:40.004843025+03:00", + "2024-12-20T13:06:50.004307995+03:00", + "2024-12-20T13:07:00.005793874+03:00", + "2024-12-20T13:07:10.005762532+03:00", + "2024-12-20T13:07:20.006582332+03:00", + "2024-12-20T13:07:30.005886582+03:00", + "2024-12-20T13:07:40.005318901+03:00", + "2024-12-20T13:07:50.003822571+03:00", + "2024-12-20T13:08:00.006378219+03:00", + "2024-12-20T13:08:10.005855688+03:00" + ] + } + ] +} +``` + +### Create task + +```bash +curl -X POST "http://localhost:7070/tasks" \ +-H "Content-Type: application/json" \ +-d '{"name": "add", "inputs": [10, 20]}' +``` + +This will output a response like the following + +```json +{ + "id": "ee8012e7-f3b1-47f1-a109-b21eb3b0e21d", + "name": "add", + "state": 0, + "inputs": [10, 20], + "start_time": "0001-01-01T00:00:00Z", + "finish_time": "0001-01-01T00:00:00Z", + "created_at": "2024-12-20T13:09:28.925730577+03:00", + "updated_at": "0001-01-01T00:00:00Z" +} +``` + +### Get a task + +```bash +curl -X GET "http://localhost:7070/tasks/e5bcc74e-9af3-4f09-b663-44dc260ab809" +``` + +This will output a response like the following + +```json +{ + "id": "1a211574-987c-4213-9266-af1640e1af95", + "name": "add", + "state": 0, + "inputs": [10, 20], + "start_time": "0001-01-01T00:00:00Z", + "finish_time": "0001-01-01T00:00:00Z", + "created_at": "2024-12-20T13:10:37.848159052+03:00", + "updated_at": "0001-01-01T00:00:00Z" +} +``` + +### Upload Wasm File + +```bash +curl -X PUT "http://localhost:7070/tasks/e5bcc74e-9af3-4f09-b663-44dc260ab809/upload" \ +-F 'file=@/build/addition.wasm' +``` + +### Start a task + +```bash +curl -X POST "http://localhost:7070/tasks/e5bcc74e-9af3-4f09-b663-44dc260ab809/start" +``` + +### Stop a task + +```bash +curl -X POST "http://localhost:7070/tasks/e5bcc74e-9af3-4f09-b663-44dc260ab809/stop" +```