Runner config with execution

docs/redirect-page.html

@@ -45,7 +45,9 @@
     <table>
       <thead>
         <tr>
-          <th scope="col" colspan="3">Digital Twin as a Service (DTaaS)</th>
+          <th scope="col" colspan="3">
+            <img src="assets/dtaas-logo-with-text.png" alt="DTaaS logo" width="600"/>
+        </th>
         </tr>
         <tr>
           <th scope="col" colspan="3">Documentation</th>

docs/user/servers/execution/runner/README.md

@@ -0,0 +1,205 @@
+# :runner: Runner
+
+A utility service to manage safe execution of remote commands.
+User launches this from commandline and let the utility
+manage the commands to be executed.
+
+The runner utility runs as a service and provides
+REST API interface to safely execute remote commands.
+Multiple runners can be active simultaneously on one computer.
+The commands are sent via the REST API and are executed on the computer
+with active runner.
+
+## :arrow_down: Install
+
+The package is available in Github
+[packages registry](https://github.com/orgs/INTO-CPS-Association/packages).
+
+Set the registry and install the package with the following commands
+
+```bash
+sudo npm config set @into-cps-association:registry https://npm.pkg.github.com
+sudo npm install -g @into-cps-association/runner
+```
+
+The _npm install_ command asks for username and password. The username is
+your Github username and the password is your Github
+[personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+In order for the npm to download the package, your personal access token
+needs to have _read:packages_ scope.
+
+## :gear: Configure
+
+The microservices requires config specified in YAML format.
+The template configuration file is:
+
+```ini
+port: 5000
+location: "lifecycle" #directory location of scripts
+```
+
+The file should be named as _runner.yaml_ and placed in the directory
+in which the _runner_ microservice is run.
+
+## :pen: Create Commands
+
+The runner requires commands / scripts to be run.
+These need to be placed in the `location` specified in
+_runner.yaml_ file. The location must be relative to
+the directory in which the **runner** microservice is being
+run.
+
+## :rocket: Use
+
+```bash
+runner # launch the digital twin runner
+```
+
+Once launched, the utility runs at the port specified in
+_runner.yaml_ file.
+
+If launched on one computer,
+you can access the same at `http://localhost:<port>`.
+
+Access to the service on network is available at `http://<ip or hostname>:<port>/`.
+
+### Application Programming Interface (API)
+
+Three REST API methods are active. The route paths and the responses given
+for these two sources are:
+
+| REST API Route                 | HTTP Method | Return Value | Comment |
+| :----------------------------- |:--------|:----------- | :------ |
+| localhost:port | POST  | Returns the execution status of command | Executes the command provided. Each invocation appends to _array_ of commands executed so far. |
+| localhost:port | GET |  Returns the execution status of the last command sent via POST request. |  |
+| localhost:port/history | GET | Returns the array of POST requests received so far. |  |
+
+#### POST Request to /
+
+Executes a command. The command name given here must exist
+in _location_ directory.
+
+=== "Valid HTTP Request"
+
+    ``` http-request
+    POST / HTTP/1.1
+    Host: foo.com
+    Content-Type: application/json
+    Content-Length: 388
+
+    {
+      "name": "<command-name>"
+    }
+    ```
+
+=== "HTTP Response - Valid Command"
+
+    ``` http-response
+    Connection: close
+    Content-Length: 134
+    Content-Type: application/json; charset=utf-8
+    Date: Tue, 09 Apr 2024 08:51:11 GMT
+    Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
+    X-Powered-By: Express
+
+    {
+      "status": "success"
+    }
+    ```
+
+=== "HTTP Response - Inalid Command"
+
+    ``` http-request
+    Connection: close
+    Content-Length: 28
+    Content-Type: application/json; charset=utf-8
+    Date: Tue, 09 Apr 2024 08:51:11 GMT
+    Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
+    X-Powered-By: Express
+
+    {
+      "status": "invalid command"
+    }
+    ```
+
+#### GET Request to /
+
+Shows the status of the command last executed.
+
+=== "Valid HTTP Request"
+
+    ``` http-request
+    GET / HTTP/1.1
+    Host: foo.com
+    Content-Type: application/json
+    Content-Length: 388
+
+    {
+      "name": "<command-name>"
+    }
+    ```
+
+=== "HTTP Response - Valid Command"
+
+    ``` http-response
+    Connection: close
+    Content-Length: 134
+    Content-Type: application/json; charset=utf-8
+    Date: Tue, 09 Apr 2024 08:51:11 GMT
+    Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
+    X-Powered-By: Express
+
+    {
+      "name": "<command-name>",
+      "status": "valid",
+      "logs": {
+        "stdout": "<output log of command>",
+        "stderr": "<error log of command>"
+      }
+    }
+    ```
+
+=== "HTTP Response - Inalid Command"
+
+    ``` http-request
+    Connection: close
+    Content-Length: 70
+    Content-Type: application/json; charset=utf-8
+    Date: Tue, 09 Apr 2024 08:51:11 GMT
+    Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
+    X-Powered-By: Express
+
+    {
+      "name": "<command-name",
+      "status": "invalid",
+      "logs": {
+        "stdout": "",
+        "stderr": ""
+      }
+    }
+    ```
+
+#### GET Request to /history
+
+Returns the array of POST requests received so far.
+Both valid and invalid commands are recorded in the history.
+
+```http
+[
+  {
+    "name": "valid command"
+  },
+  {
+    "name": "valid command"
+  },
+  {
+    "name": "invalid command"
+  }
+]
+```
+
+## :balance_scale: License
+
+This software is owned by
+[The INTO-CPS Association](https://into-cps.org/)
+and is available under [the INTO-CPS License](./LICENSE.md).

mkdocs-github.yml

@@ -51,6 +51,7 @@ nav:
       - Digital Twins: 
           - Create: user/digital-twins/create.md
           - Lifecycle: user/digital-twins/lifecycle.md
+      - Runner: user/servers/execution/runner/README.md
       - Examples:
           - Overview: user/examples/index.md
           - Mass Spring Damper: user/examples/mass-spring-damper/README.md

mkdocs.yml

@@ -51,6 +51,7 @@ nav:
       - Digital Twins: 
           - Create: user/digital-twins/create.md
           - Lifecycle: user/digital-twins/lifecycle.md
+      - Runner: user/servers/execution/runner/README.md
       - Examples:
           - Overview: user/examples/index.md
           - Mass Spring Damper: user/examples/mass-spring-damper/README.md

script/docs.sh

@@ -23,6 +23,8 @@ printf "generate and publish documents"
 mkdocs build --config-file mkdocs.yml --site-dir "site/online/${VERSION}"
 
 cp docs/redirect-page.html site/index.html
+mkdir site/assets
+cp docs/assets/dtaas-logo-with-text.png site/assets/.
 
 cd "${TOP_DIR}" || exit
 git checkout webpage-docs
@@ -47,6 +49,7 @@ fi
 
 cd "${TOP_DIR}" || exit
 mv site/index.html .
+mv site/assets .
 rm -rf site
 
 git add .

servers/execution/runner/DEVELOPER.md

@@ -0,0 +1,59 @@
+# :runner: Developer Instructions
+
+This microservice needs a configuration file.
+Please see [README](./README.md) for this information.
+
+## :hammer_and_wrench: Developer Commands
+
+```bash
+yarn install    # Install dependencies for the microservice
+yarn syntax     # Analyze code for errors and style issues
+yarn graph      # Generate dependency graphs in the code
+yarn build      # Compile ES6 to ES5 and copy JS files to build/ directory
+yarn test       # Run tests
+yarn test:nocov # Run the tests but do not report coverage
+yarn test:watchAll # Watch changes in test/ and run the tests
+yarn start      # Start the application
+yarn clean      # Deletes directories "build", "coverage", and "dist"
+```
+
+## :package: :ship: NPM package
+
+### Github Package Registry
+
+The Github actions workflow of
+[lib microservice](../../../.github/workflows/runner.yml) publishes the **runner**
+into
+[packages](https://github.com/orgs/INTO-CPS-Association/packages?repo_name=DTaaS).
+
+### Verdaccio - Local Package Registry
+
+Use the instructions in
+[publish npm package](../../../docs/developer/npm-packages.md) for help
+with publishing **runner npm package**.
+
+Application of the advice given on that page for **runner** will require
+running the following commands.
+
+### Publish
+
+```bash
+yarn install
+yarn build #the dist/ directory is needed for publishing step
+yarn publish --no-git-tag-version #increments version and publishes to registry
+yarn publish #increments version, publishes to registry and adds a git tag
+```
+
+### Unpublish
+
+```bash
+npm unpublish  --registry http://localhost:4873/ @into-cps-association/[email protected]
+```
+
+## :rocket: Access the service
+
+## Service Endpoint
+
+The URL endpoint for this microservice is located at: `localhost:<port>`
+
+Please see [README](./README.md) for more information.