README + env variable naming (#18)

* readme + some env renaming

* version bump

* remove references to QEMU in readme

* typos

* revert linting

* Revert "revert linting"

This reverts commit b988323.

* try again on revert linting

README.md

@@ -1,29 +1,55 @@
-# Morello-API
-The interface for executing binaries on morello board and self that returns output which can be processed by the client.
+# morello-api
 
+## Description
 
-## Local
-Update your local.json to contain a variable for your QEMU morello-purecap system **morello.address**. File mmight not be created just yet, so you would need to create one in `./config/` folder and add a new properrty, please look at the `default.json` on how other variables are configured. If you would like to connect using, then you would need to run quemu with `--run/ssh-forwarding-port=2222` switch so it woould look something like -> `./cheribuild.py run-morello-purecap --run/ephemeral --run/ssh-forwarding-port=2222 -d` and then connect `ssh -p 2222 localhost`. For uploading files `scp -v -P 2222 <FILE> localhost:/tmp`.
+A `Node.js` API for executing binaries on Morello and `aarch64` architecture. Requires an instance of Morello e.g. [Morello SDK](https://github.com/CTSRD-CHERI/cheribuild). The API copies binaries to the Morello instance, executes them and returns the output.
+
+## Configuration
+
+Use a `.env` at root of the repository to set values for the environment variables defined in [custom-environment-variables.json](./config/custom-environment-variables.json).
+
+| variable         | required |   default   | description                                                                          |
+| :--------------- | :------: | :---------: | :----------------------------------------------------------------------------------- |
+| PORT             |    N     |   `3000`    | The port for the API to listen on                                                    |
+| LOG_LEVEL        |    N     |   `debug`   | Logging level. Valid values are [`trace`, `debug`, `info`, `warn`, `error`, `fatal`] |
+| MORELLO_HOST     |    N     | `127.0.0.1` | Morello host name                                                                    |
+| MORELLO_PORT     |    N     |   `1022`    | Morello port                                                                         |
+| MORELLO_USERNAME |    N     |   `root`    | Morello username                                                                     |
+
+[default.json](./config/default.json) contains default configuration values.
+
+Alternatively create a `./config/local.json` file to override the values of `default.json`.
+
+## Binaries
+
+Binaries to be executed by the API are located in the [bin](./bin/) directory, however the API is primarily designed to be used as a docker image. [Dockerfile](./Dockerfile) replaces the contents of `bin` with the latest binaries from [`morello-examples`](https://github.com/digicatapult/morello-examples), a separately maintained list of examples designed to illustrate how certain common software defects can be protected against by running on a Cheri-enabled platform.
+
+Some simple binaries are included in this repository for local testing. Binaries can also be added manually to the `bin` directory. Each binary will need its filename added to the [`Executables`](./types/models/scenario.ts) type to appear as an option on the API route.
+
+## Getting started
 
 ```sh
- # 1. install dependenciees
+ # start dependencies
+docker compose up -d
+ # install packages
 npm i
- # 2. generate swagger and route files for Open API
+ # generate swagger and route files for Open API
 npm run build
- # 3. start service in dev mode. In order to start in full - npm start"
-npn run dev
+ # start service in dev mode. In order to start in full - npm start"
+npm run dev
 ```
 
-#### SSH Configuration
-> .ssh/known_hosts
+View OpenAPI documentation for all routes with Swagger:
 
-> confirming
+```
+localhost:3000/swagger/
+```
 
 ## Tests
-So far we have two tests **unit** and **integration** each could be executed by calling the below commands
+
+**Unit** and **integration** test are executed by calling the following commands:
+
 ```sh
 npm run test:integration
 npm run test:unit
 ```
-
-To be updated....

config/custom-environment-variables.json

@@ -3,7 +3,7 @@
     "LEVEL": "LOG_LEVEL"
   },
   "morello": {
-    "address": "MORELLO_HOST",
+    "host": "MORELLO_HOST",
     "username": "MORELLO_USERNAME",
     "port": "MORELLO_PORT"
   },

config/default.json

@@ -3,9 +3,9 @@
     "level": "debug"
   },
   "morello": {
-    "address": "127.0.0.1",
+    "host": "127.0.0.1",
     "username": "root",
-    "port": 22
+    "port": 1022
   },
   "app": {
     "port": 3000

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digicatapult/morello-api",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "An interface for executing binaries on it's self and morello host.",
   "main": "src/index.ts",
   "scripts": {

src/controllers/scenario/__tests__/index.test.js

@@ -7,7 +7,7 @@ const { expect } = require('chai')
 const child = require('child_process')
 const config = require('config')
 
-const address = `${config.get('morello.username')}@${config.get('morello.address')}`
+const address = `${config.get('morello.username')}@${config.get('morello.host')}`
 const port = config.get('morello.port')
 
 const execute = async () => {

src/controllers/scenario/index.ts

@@ -22,7 +22,7 @@ export class scenario extends Controller implements IScenario {
 
   constructor() {
     super()
-    this.address = `${config.get('morello.username')}@${config.get('morello.address')}`
+    this.address = `${config.get('morello.username')}@${config.get('morello.host')}`
     this.port = config.get('morello.port')
     this.log = Logger.child({ controller: '/scenario', ...config.get('morello') })
   }