fb-runner-node

Form Builder Runner renders forms from configuration data to capture user submissions.

For more information, read the Runner’s documentation.

Pre-requisites

Node >= 14.20.1 <15.0.0

Installation

git clone [email protected]:ministryofjustice/fb-runner-node.git
cd fb-runner-node
npm install

Usage

The SERVICE_PATH environment variable describes the location on your file system of the form for Runner to use.

To set the SERVICE_PATH environment variable, open a terminal and change into the root directory of Runner, then execute the command:

SERVICE_PATH=[path to form] npm start

(Where [path to form] is a path to the location on your file system of the form. An Example Service form can be cloned from https://github.com/ministryofjustice/fb-example-service.)

By default, Runner will start on localhost port 3000. To run on a different port, set the PORT environment variable:

PORT=4321 SERVICE_PATH=[path to form] npm start

Using Runner with Mock Services

Use fb-mock-services to mock services for Runner.

Clone the fb-mock-services repository and start the Mock Services app according to the instructions supplied there.

In Runner, create an .envmocks file at the root of the project:

export SERVICE_SLUG=slug
export SERVICE_SECRET=secret
export SERVICE_TOKEN=token
export SUBMISSION_ENCRYPTION_KEY=key
export USER_DATASTORE_URL=http://localhost:44444
export USER_FILESTORE_URL=http://localhost:44445
export SUBMITTER_URL=http://localhost:44446

Open a terminal and change into the root directory of Runner then execute the command:

source .envmocks && SERVICE_PATH=[path to form] npm start

(Where [path to form] is a path to the location on your file system of the form.)

Using Runner with Docker Services

Use fb-acceptance-tests to mock services for Runner.

Clone the fb-acceptance-tests repository and execute the make serve command according to the instructions supplied there.

In Runner, create an .envmocks file at the root of the project:

export SERVICE_SLUG=slug
export SERVICE_SECRET=secret
export SERVICE_TOKEN=token
export USER_DATASTORE_URL=http://localhost:10001
export USER_FILESTORE_URL=http://localhost:10002
export SUBMITTER_URL=http://localhost:10003
export ENCODED_PRIVATE_KEY=[encoded private key]
export ENCODED_PUBLIC_KEY=[encoded public key]

Where [encoded private key] and [encoded public key] are the same as the values supplied to the services in the docker-compose.yml file at the root of the fb-acceptance-test project. (Currently, they are also contained in .env.example file at the root of this project.)

Open a terminal and change into the root directory of Runner then execute the command:

source .envmocks && SERVICE_PATH=[path to form] npm start

(Where [path to form] is a path to the location on your file system of the form.)

Testing

npm test

Linting

npm run lint

Debugging

Node inspector can be enabled for debugging.

Open a terminal and change into the root directory of Runner then execute the command:

PORT=4321 SERVICE_PATH=[path to form] node inspect bin/start

(Where [path to form] is a path to the location on your file system of the form.)

Note that the start command is not npm start.

The breakpoint statement debugger can then be placed in file to trigger the inspector.

Deploying to Cloud Platforms

See deployment instructions.

Module Aliases

Some module paths are aliased.

At runtime they are resolved with @ministryofjustice/module-alias. (Its definitions can be found in the _moduleAliases {} field on package.json.)

During development aliases can be resolved in different ways according to needs of the developer's IDE. A solution we provide is via Webpack, which is supported automatically in WebStorm and related IDEs, or with some manual steps.

At start-up WebStorm will report in the Event Log that "Module resolution rules from webpack.config.js are now used for coding assistance" if the configuration is automatically identified -- if not, follow the manual steps:

1. Right-click on the lib directory and select Mark Directory as > Resource root
2. From the application menu select Preferences > Languages & Frameworks > JavaScript > Webpack then in the right-hand pane use the file browser to select webpack.config.js from the package root

You shouldn't need to restart but it won't hurt.