diff --git a/README.md b/README.md index f5679a9..4286e3a 100644 --- a/README.md +++ b/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 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.... \ No newline at end of file diff --git a/config/custom-environment-variables.json b/config/custom-environment-variables.json index 364eb25..6601e77 100644 --- a/config/custom-environment-variables.json +++ b/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" }, diff --git a/config/default.json b/config/default.json index 1c11c33..8325ac6 100644 --- a/config/default.json +++ b/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 diff --git a/package-lock.json b/package-lock.json index b4f07c2..3c5e317 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@digicatapult/morello-api", - "version": "0.6.2", + "version": "0.6.3", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@digicatapult/morello-api", - "version": "0.6.2", + "version": "0.6.3", "license": "Apache-2.0", "dependencies": { "body-parser": "^1.20.0", diff --git a/package.json b/package.json index dfca5e4..832224a 100644 --- a/package.json +++ b/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": { diff --git a/src/controllers/scenario/__tests__/index.test.js b/src/controllers/scenario/__tests__/index.test.js index 3ad1cf8..d8d5de3 100644 --- a/src/controllers/scenario/__tests__/index.test.js +++ b/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 () => { diff --git a/src/controllers/scenario/index.ts b/src/controllers/scenario/index.ts index c64d6b3..5b099d2 100644 --- a/src/controllers/scenario/index.ts +++ b/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') }) }