Skip to main content

Local Backend

Overview​

For both Native and Web we have the ability to run a local instance of the Backend service. This allows developers to have their own environment for creating users/data without affecting anyone else. It also means that we don't bog down the Staging/Production databases with test and fake data.

Prerequisites​

In order to run the script successfully the following dependencies are required:

  1. Homebrew
  2. Git
  3. Git authentication setup through SSH

Launch the Backend​

We have a series of scripts that can be ran in order to spool up a local backend.

  1. Run the script to start the local backend from the project root:
yarn backend:start

This script will ask you which branch you want to start, initially it will display main and other, the latter will allow you to provide a string for the branch name you want to clone.

  1. When the script is ran it will alert you of any missing dependencies such as Docker and will attempt to install using Homebrew. The following will be installed if not already:

    • Docker
    • Tilt
    • Ko
    • Go

  2. The script will clone the Backend repo and create a new ./temp/backend-repo folder in the root of the project. This folder is ignored by Git.

  3. Once the backend has successfully spooled up you should see a ✅ Backend is up and running! message in the terminal you ran the start script on.

  4. This script will automatically also attempt to create your Root user account. Its likely at this point it will fail unless you have a local instance of the Web project already running. This isnt a problem as the Root user can be created seperately when you're ready.

Stop the local Backend​

You will occasionally need to stop your existing local backend in order to get the latest backend changes, to switch to a different backend branch or to clear down your data to start with a blank slate. To stop the backend you can simply run yarn backend:stop which will kill the backend process.

Running this will also delete your .rootuser.json file from the current instance. These details are no longer any use with the service being killed.

Test data​

When the local backend is created it is created empty, as such it will be common that you'll need a Root user, orgs and several client users to login with and action something.

Root User​

The Root user account is the base account that everything stems from. You need the Root account to begin creating items within the new environment. There can only ever be 1 Root user account, if a second account is attempted to be created it will fail creation. It should also be noted that we need to persist these root details for local development in order to allow us to continue running e2e tests, for this reason when a Root user is created we store the credentials in a .rootuser.json file located in the /temp/backend-repo directory.

When logging into the Root user account you will be logged into the Admin Portal instead of the Client Portal.

Creating a Root user​

A Root user can be created in 1 of several ways:

  • A new user will be attempted to be created during yarn backend:start however it will fail if a local instance of the web project is not running at the time.
  • You can run yarn backend:create-root to directly create a root user, if the root user already exists this call will print the existing root user (assuming we can find the details in the local .rootuser.json file)
  • You can run yarn backend:create-org to create a new organisation which will also attempt to create a new root user too (See Organisations below for more information).
  • Running an e2e test will also trigger the creation of the Root user however it should be noted if you run yarn workspace web e2e it will attempt to run the tests in parallel which will ultimately lead to some failures (if the Root user does not exist) as it'll trigger multiple calls to create the Root user and only 1 will succeed.

Organisations​

With a new environment and a new Root user setup you'll now need to create an organisation to work from and create users under.

When setting up an organisation it is a requirement that we also create a new Owner user who owns that organisation. We can create additional Owner accounts for the org later on but the Owner we create at this point is the Primary Owner of the organisation and cannot be changed.

Creating an organisation​

A new Organisation can be created by calling yarn backend:create-org. Calling this script it will ask you a few questions:

  • Do you want to create a random or custom organisation?
    • A Random organisation will randomly generate your organisation details such as org name, country, currency etc
    • A Custom organisation will require you to specify certain information
  • Select the users you would like to create
    • You have the option here to selected/unselect the users that you want. Unless you require otherwise, its usually a good idea to keep all selected.

Once the script is ran it will output all the information in the terminal window including:

  • New Orgnaisation information
  • Your Root user details
  • Your Organisation Owner user details
  • Your Organisation User details

Where 2FA is enabled for the organisation you will also see QR codes displayed in the terminal under the user it aligns with. You can scan this code with your 2FA authentication app (Such as Google Authenticator) to generate a 2FA code to allow you to login to the account.

Scripts​

To make life easier we have created several easy to use scripts outlined below:

  • yarn backend:create-root

    This script will create a new Root user if one does not already exist and print the results, or if one already exists and we have the details local in our .rootuser.json file then we'll simply print those details to the terminal. See Creating a Root user for more details.

  • yarn backend:create-org

    This script will create either a randomly generated or a custom new organisation in your environment along with multiple new user accounts. All items created will be output in the terminal. See Creating an organisation for more details

  • yarn backend:create-workspace

    This script will create 1 or more workspaces in your environment and will output all created into the terminal.

  • yarn backend:create-user

    This script will create a single user account of any role in a particular workspace in your organisation. It will then automatically authenticate with the credentials to fetch a valid session token so you can generate and use the account instantly (Assuming what you're after is the session token - otherwise you can login to the account as usual through the web portal)

  • yarn backend:create-case

    This script will create a new Case within your organisation

  • yarn backend:create-asset

    This script will generate a given quantity of new Assets, assign them to the chosen Case and Subject, based on a specified Category:

    • Random - Will randomly select a category for each asset created
    • Digital - Will create Digital assets only
    • Fiat Cash - Will create Fiat Cash assets only
    • Personal Property - Will create Personal Property assets only
    • Real Estate - Will create Real Estate assets only
    • Vehicle - Will create Vehicle assets only

In order for these create scripts to be ran you must first start a local instance of the web, this can easily be achieved by calling:

yarn workspace web start:local

Issues​

Docker Cache Issues​

Occasionally Dockers cache needs to cleared down in order to successfully start a new instance of the backend service. This can be done by:

  1. Stopping the currently service using yarn backend:stop
  2. Deleting the /temp folder from the Frontend project
  3. Running docker system prune -a --volumes -f to clear dockers cache in full

Monitor Logs​

It can be useful to monitor the local backend to ensure calls are correctly making their way through. You can view the logs inside of Docker.