Environment Setup

Login to Bit

Once bit is installed, you need to login, run the command below and get the password from Lastpass (search for bit)

bit login

user: HectarePlatform
password: [IN LASTPASS]

You can read more about Bit here https://bit.dev/docs/quick-start

Please read about how we use Bit as part of our developer workflow here

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 an environment variable which is used to initialise the configuration system and decrypt sensitive values

export HECTARE="[PLEASE GET VALUE FROM A BACK END DEVELOPER]"

This 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
$ bit install # install dependencies
$ 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

All of our code is encapsulated in Bit managed components. This means we are generally referencing our components via node_modules rather than relative paths, for example

import { Context } from '@hectare/platform.components.context'

not

import { Context } from '../../components/context'

Bit manages compilation of our typescript and keeps our components in node_modules up to date as we're coding, but for this to work you need to run bit watch in a terminal window while you are working. You should run this command whenever you are coding / running the APIs

pnpm run watch

Its important not to forget to have a separate terminal running the watch command otherwise you'll be wondering why your code changes dont seem to be having any effect!

Referencing our components in this way also impacts debugging, key is to ensure we are generating sourcemaps and providing the correct paths to our transpiled code and their associated sourcemaps in order for us to be able to debug our source typescript files.

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

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.

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

Debugging tests is a little different, we've got this working with the following approach

1. Ensure your vscode Auto Attach setting is set to Always
2. Open a JavaScript Debug Terminal
3. Put a breakpoint in the test you want to debug
4. In the debug terminal trigger the tests in the component you want to debug, i.e.

bit test components/search --debug

Your breakpoint should be hit

When running locally 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

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