Environment Setup

Host Entry

Please add the following entry to your hosts file so we can run the API on a Hectare domain locally

local.hctr.io

1. Open terminal
2. run "sudo nano /etc/hosts"
3. add the following to a new line in the hosts file

  127.0.0.1       local.hctr.io

4. Save and close the file

Installation

Once you have installed the prerequisites you need add 2 environment variables which are used to initialise the configuration system and decrypt sensitive values

export HECTARE_OVERRIDES="/[PATH_TO_REPOSITORY]/overrides.json"
export HECTARE="[PLEASE GET VALUE FROM A BACK END DEVELOPER]"

HECTARE_OVERRIDES points to your configuration overrides files, see below for more info HECTARE env var is a base64 encoded string of the following JSON

{
  "key": "[SECRET]",
  "environment": "dev",
  "salt": "[SECRET]"
}

key and salt are used for encrypting secrets in the configuration, these are different for each environment.

You need to add an environment variable to ensure the integration tests use the correct Cognito UserPool

export AWS_COGNITO_USER_POOL_ID="eu-west-2_iF043jIyZ"
export AWS_COGNITO_API_CLIENT_ID="5civehrtqe1shdtqurfei6dtm"
export AWS_REGION="eu-west-2"

When thats done you can run the following commands to get everything running

$ cd path_to_repo
$ git clone https://github.com/Hectare-Agritech/platform.git
$ cd platform
$ pnpm i
$ pnpm run build # generates OpenAPI types, builds and runs tests
$ pnpm run dev # starts the services/local which is a local API which is configured to run all modules

Configuration Overrides

Each developer needs an overidden configuration setting for their local environment, which allowws us to create databases and other resources specific to each developer, you need to add the following settings to your local config overrides file. If you have not set up your local overrides, please read about how to do this in the configuration docs

{
  "developer": "[YOUR_NAME]",
  "insights.enabled": false,
  "insights.connection.database": "insights",
  "whitelist.phones": "[YOUR_PHONE_NUMBER]",
  "tests.aws.cognito.clientId": "5civehrtqe1shdtqurfei6dtm",
  "tests.aws.cognito.userPoolId": "eu-west-2_iF043jIyZ"
}

Running & Debugging APIs & Tests

When running locally we combine all modules into a single API Server in order to simplify the development process, therefore the whole platform will run from a single endpoint

http://local.hctr.io:8001

To run the app and attach the debugger in vscode follow these steps.

pnpm run dev

This will start the app and start the debugger on port 9001. You can then put breakpoints in the source typescript code where necessary and attach the debugger to the node process.

For vscode there are 2 launch configurations, one to debug tests and one to attach to the running NodeJS application, please see ./vscode/launch.json for specifics.

To attach to process...

1. Click the 'Run and Debug' menu icon in vscode
2. Choose 'Attach' from the dropdown
3. Click the Play icon to attach to the debugger
4. Trigger the API

To debug a test...

1. Open the test file you want to debug
2. Put a breakpoint on the test
3. Click the 'Run and Debug' menu icon in vscode
4. Choose 'Debug test' from the dropdown
5. Click the Play icon to run the tests, your breakpoint shoult be hit

Debug Startup Process

You may need to debug the startup process rather than attaching to already running process. There is another launch configuration to allow you to do this called Debug Local Startup. Simply add a breakpoint to the startup code where required, ensure your local process is not already running and choose Debug Local Startup from the dropdown menu on the debug tab

Running Event Handlers Locally

When we run the API locally we inject the LocalEventBus into the context which instead of publishing the event to AWS will simple trigger the event in process at the time it would otherwise have been published.

This means all event handlers will run by default locally without the need for any further configuration or setup