Local Workbench Environment Setup Guide¶

Overview¶

This guide walks you through setting up your local development environment for the Send Workbench. Follow each section in order — some steps depend on earlier ones being complete.

Step 1: Connect to VPN¶

Before anything else, make sure NordVPN is installed and you're connected. You'll need it to access Bitbucket, AWS, and other internal tools throughout this setup.

Step 2: Install Core Apps¶

Install the following tools one by one. Links are included for each.

2a. Google Chrome¶

Download from chrome.google.com if not already installed.

2b. Homebrew (package manager)¶

Open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen prompts. This makes installing other tools much easier.

2c. Oh-My-Zsh (nicer terminal — recommended)¶

In Terminal, run:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

This improves your terminal experience. Most instructions in this guide reference the .zshrc file it creates.

2d. IntelliJ IDEA (Java IDE)¶

Download from jetbrains.com/idea. Choose the Ultimate edition and activate it with your company licence.

2e. SDKMAN (Java version manager)¶

In Terminal, run:

curl -s "https://get.sdkman.io" | bash

Then close and reopen Terminal, and install Java and Gradle:

sdk install java
sdk install gradle

2f. NVM + Node.js (Node version manager)¶

In Terminal, run:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Then close and reopen Terminal, and install Node v24:

nvm install 24
nvm use 24

2g. Docker Desktop¶

Download from docker.com/products/docker-desktop. Install and open it — it needs to be running in the background for Redis and the Search Service to work.

2h. MySQL 8.0.34¶

Download version 8.0.34 from dev.mysql.com/downloads. Run the installer and follow all prompts.

If MySQL doesn't start automatically, run this in Terminal:

sudo /usr/local/mysql/support-files/mysql.server start

Step 3: Update Your Hosts File (CRUCIAL)¶

This step is required — without it, your local environment will not start.

Open Terminal and run:
```
sudo nano /etc/hosts
```
You'll be prompted for your Mac password. Enter it.

Scroll to the bottom of the file and add this line:

127.0.0.1 riskwire 127.0.0.1 riskwire-hub 127.0.0.1 socket-io 127.0.0.1 riskwire-rest-in 127.0.0.1 riskwire-rest-out 127.0.0.1 mysql

Press Ctrl + X, then Y, then Enter to save.

Step 4: Set Up Artifactory Credentials¶

Artifactory is used to pull internal code dependencies. You need to add your credentials to your shell config file.

Open Terminal and run:
```
nano ~/.zshrc
```
Scroll to the bottom and add:
```
export artifactory_user=your.name@send.technology
export artifactory_password=YOUR_ARTIFACTORY_PASSWORD
```
(Replace with your actual credentials — ask the team if you don't have them yet.)
Press Ctrl + X, then Y, then Enter to save.
Reload the file:
```
source ~/.zshrc
```

Step 5: Set Up AWS Access¶

Request new AWS access keys by following the instructions in the email you received.
Once you have access, log into the AWS console and navigate to DynamoDB in the eu-west-2 (London) region.
Go to Explore Items → env-config.
Select Query and search for dev.salesEngineerTemplate. Open the result and copy the entire file contents.
Click Create Item and name it dev.yourName (e.g. dev.garikai).
Paste the contents from dev.salesEngineerTemplate into your new item.
Inside the file, search for "yourName" — replace every occurrence with your actual name (e.g. garikai).
Also update the reference to dev.salesEngineerTemplate to be dev.yourName.
Save the item.

Step 6: Set Up Bitbucket SSH Access¶

This lets you download (clone) code repositories securely.

Generate an SSH key:

ssh-keygen -t ed25519 -C "your.email@send.technology"

Press Enter through the prompts (adding a passphrase is optional).

Add it to your Mac's keychain:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Configure SSH:

touch ~/.ssh/config
chmod 600 ~/.ssh/config

Open the file:

nano ~/.ssh/config

Add the following:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Save with Ctrl + X, then Y, then Enter.

Copy your public key:

pbcopy < ~/.ssh/id_ed25519.pub

Add it to Bitbucket: 1. Go to bitbucket.org → Your Profile → Personal Settings → SSH Keys 2. Click Add Key and paste it in.

Test the connection:

ssh -T git@bitbucket.org

You should see a success message.

Step 7: Clone the Repositories¶

Navigate to wherever you'd like to store your code (e.g. ~/code) and clone the following:

# Core backend
git clone git@bitbucket.org:sendtech/riskwire.git

# Core frontend
git clone git@bitbucket.org:sendtech/uw-workbench.git

# UK client config
git clone git@bitbucket.org:sendtech/send-senduk.git

# US client config
git clone git@bitbucket.org:sendtech/send-sendus.git

After cloning, ask the team which branch/version to check out. Then for each repo, switch to that branch.

For riskwire, run:

cd riskwire
./gradlew clean build --refresh-dependencies

(This will take a few minutes the first time.)

For uw-workbench, run:

cd uw-workbench
npm ci

Step 8: Create Your Local Database¶

Make sure MySQL is running.
Open the file at: send-senduk/data-storage/sql/init/create-database.sql
Run it against your local MySQL instance to create the required databases. (You can do this via a database tool like IntelliJ's built-in DB tool, MySQL Workbench, or the terminal.)

Step 9: Seed Your S3 Bucket with Config Data¶

You need to push config files to your personal S3 bucket on AWS. In Terminal:

Core config:

cd riskwire/config/core
aws s3 sync --exclude ".*" . s3://agateway.client.config.london.yourName/core

UK client config:

cd send-senduk/config/senduk
aws s3 sync --exclude ".*" . s3://agateway.client.config.london.yourName/senduk

Test config (required for the dummy login user):

cd send-senduk/config/test
aws s3 sync --exclude ".*" . s3://agateway.client.config.london.yourName/test

Replace yourName in all S3 paths with your actual name, matching what you set in DynamoDB.

Step 10: Run the Backend Services (via IntelliJ)¶

For each service below, you'll need to add environment variables before running:

In IntelliJ, right-click the service in the Services tab → Edit Configuration
Click Modify Options → Environment Variables
Add: envId=dev.yourName;disable-security=true;

Run services in this order:

Order	Service	Notes
1	`Main` (agateway / riskwire-hub)	Run this first — it sets up the schema
2	`UnderwritingManagementApp`	Main service for Workbench functionality
3	`RatingServiceMain`
4	`RulesEngineMain`
5	`UserManagementServiceMain`
6	`ClientAPIMain`
7	`AssetManagementApp`	Only needed if working with assets
8	`PipelineServiceMain`

After running Main for the first time: Go into DynamoDB and delete the forceReloadOfPipelines config entry — you don't want it reloading every time you start up.

Minimum services needed for basic use: - Main - UnderwritingManagementApp - PipelineServiceMain - ClientAPIMain

Step 11: Run the Client Service¶

This is where most of the demo work happens.

Run RiskwireSendUkMain (or RiskwireSendUsMain for US demos)
Add the same environment variables as the other services: envId=dev.yourName;disable-security=true;

Step 12: Run the Frontend¶

Open Terminal and navigate to where you cloned uw-workbench
Run:
```
npm run start:local
```
The app should open in your browser.

You're Done!¶

At this point your local environment should be up and running. A few tips to keep things smooth:

Re-push your S3 config often. If config files get deleted centrally, your S3 bucket won't update automatically — delete and re-push periodically to stay in sync.
Keep branch names generic. Avoid naming branches after specific clients (e.g. use some-feature-changes not client-x-demo).
Learn your IntelliJ shortcuts. Cmd + Opt + L formats code, Ctrl + Opt + O cleans up imports, and Cmd + Shift + O lets you search for classes by initials (e.g. type SRFC to find SomeRandomFunctionController).