Introduction

Important setup instructions to note before contributing to the project.

Prerequisites

Some software we need to get started developing (if you don't have them already)

• NodeJS >= 18.x.x

• NPM

• Docker

• Ngrok

Developer Setup

Please follow the following instructions to setup the environment properly for development. There will be instructions for Windows and MacOS.

1. Install NodeJS (at least version 18). The NPM package manager will be installed with NodeJS.

   1. (optional) Installing a version manager (e.g. nvm, asdf) to manage multiple versions of Node. Since you will generally only be using one version, this doesn't really matter but it may be helpful.

Here are some popular version managers you may use if you wish

https://github.com/nvm-sh/nvm (Linux, MacOS, WSL)

https://github.com/coreybutler/nvm-windows (Windows native support)

https://asdf-vm.com/ (Linux, MacOS)

Node.js — Download Node.js®nodejs.org

https://nodejs.org/en/download

You may also opt to use another JS runtime like Deno or Bun and another package manager like Yarn or PNPM, but we do not guarantee they work (and please do not commit any lockfiles to Git).

1. Install Docker. We recommend you install Docker Desktop to have the GUI.

Docker Desktop: The #1 Containerization Tool for Developers | DockerDocker

https://www.docker.com/products/docker-desktop/

1. Install Ngrok. This is solely to tunnel Shopify test requests back to localhost in development and is not used in production. You will only need to use this when testing Shopify checkout related workflows.

Download ngrokngrok.com

https://ngrok.com/download

Running on localhost

Now we are ready to setup the codebase and run the application for the first time.

If you want to see specific and concise instructions for either the frontends or backend, see Frontend Setupor Backend Setup respectively.

Also later visit Aliasesto see useful aliases to perform the below setup quicker.

We highly recommend you walk through these steps on your first time to understand everything.

1. Clone the repository.

git clone https://github.com/leofuturer/eDrops3.git
cd eDrops3

Then make sure you have the latest environment variables in the deploy/ folder. These should be in Google Drive for you to download. Contact a codeowner if you need assistance.

1. Choose a frontend to work on (main site, community site). Here we use the main site which is in the client/ folder.

cd client

1. Install all packages first. This may take a while if its the first time and no packages are cached.

npm install

1. Run the frontend

npm run dev

Now you should be able to visit localhost:8086 to view the main site.

Note the community site runs on port 8087 instead, so localhost:8087

Many features that require the backend will not work (e.g. login, view products, etc.), so now we will start the backend.

1. We want to leave the frontend running. So in a new terminal, enter the server/ directory where the backend code is.

cd server

1. Build the docker container for the backend. See for a crash course on what Docker is and how to use it.

docker build -t edroplets_backend .

1. Pull the docker images for MySQL and Ngrok respectively from the Docker container repository. These are for the MySQL database and Ngrok tunnel for development.

docker pull mysql:8
docker pull ngrok/ngrok:latest

1. Now we can use docker-compose to stand up all the backend services.

The compose files are in the root of the project. So go back to the root if needed, i.e. with

cd ..

The first time we run this we want to seed the database (initialize it with data). So we add additional environment variables. On subsequent runs you do not need to do this and you probably don't want to do it as it resets the database.

Windows

$env:RESET_DATABASE = 'Yes'; $env:MIGRATE_DATABASE = 'Yes'; docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d; $env:RESET_DATABASE = ''; $env:MIGRATE_DATABASE = ''; docker-compose -f docker-compose.yml -f docker-compose.dev.yml logs -f

Linux/MacOS

RESET_DATABASE=Yes MIGRATE_DATABASE=Yes docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d && docker-compose -f docker-compose.yml -f docker-compose.dev.yml logs -f

The first time the MySQL container is created, the database needs to be created, so this command may take some time. Please be patient and wait until you receive the message:

edrop_backend  | Server is running at http://127.0.0.1:3000

Once the backend is running, you may find useful information at the following locations:

• localhost:3000: Loopback 4 home

• localhost:3000/explorer: shows OpenAPI spec explorer

• localhost:4040: shows the Ngrok tunnel URL and interface (to track incoming HTTP/S requests)

• Any uploaded files appear in the server/storage/ folder.

Voila! Now if you visit the frontend page at localhost:8086 again, you should see everything working. Login with the below test login:

username: customerA
password: edropTest123

See the see data in the folder server/src/lib/data/ for additional logins. e.g. all test customer logins are in server/src/lib/data/customer.ts

If anything does not work, please double check you have the correct environment variables, visit Troubleshooting, or contact a codeowner for assistance.