Backend Setup

Setup and run the backend

Setup

Open a new terminal window. The first step is to build the backend container which runs the REST API and download container images for MySQL and Ngrok, the other services that we will be running as part of our Docker stack.

  • If you are not developing checkout-related features, running Ngrok is optional.

Build backend Docker stack
cd server
docker build -t edroplets_backend .
docker pull mysql:8.0
docker pull ngrok/ngrok:latest

A potential issue you may run into is some sort of permission denied error (typically looking something like this message) when you are running the backend or trying to use persistent data storage

EACCES: permission denied

This generally happens if you run Docker without sufficient privileges. On Windows try running Docker as administrator and on MacOS/Linux try running docker under sudo.

Now create the following files in deploy/dev to supply environment variables to the containers. Ask a codeowner for a copy of these files as they contain sensitive information.

Add environment variables
cd deploy/dev/
touch backend.env mysql.env ngrok.env

The files should look something like this (except with the values populated):

deploy/dev/backend.env
NODE_ENV=dev  
  
APP_MYSQL_DATABASE=  
APP_MYSQL_USERNAME=  
APP_MYSQL_PASSWORD=  
APP_MYSQL_HOST=  
APP_MYSQL_PORT=  
  
APP_EMAIL_HOST=
APP_EMAIL_PORT=
APP_EMAIL_USERNAME=
APP_EMAIL_API_KEY=  

APP_PUSHER_API_ID=
APP_PUSHER_API_KEY=
APP_PUSHER_API_SECRET=
APP_PUSHER_API_CLUSTER=
  
SHOPIFY_DOMAIN=
SHOPIFY_TOKEN=
deploy/dev/mysql.env
MYSQL_ROOT_PASSWORD=  
MYSQL_DATABASE=  
MYSQL_USER=  
MYSQL_PASSWORD=
deploy/dev/ngrok.env
NGROK_AUTHTOKEN=

Run

Now go back to the top level directory where all the docker-compose.*.yml files reside to initialize the database and add seed data.

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
MacOS/Linux
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

  • RESET_DATABASE = Yes indicates the completely wipe and recreate the database from scratch, then reseed it

  • MIGRATE_DATABASE = Yes updates the database schema and you will need to run this if either you are running the backend for the first time, or changed a backend model (added/removed fields or modified the types of fields of some table)

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

Now that you have initialized the database and setup the backend for the first time you may run the following commands to startup the backend each time without resetting and migrating the database schema.

Windows
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
MacOS/Linux
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

To explain the docker compose commands, the -f option selects the docker compose files to run (in this case the base file which runs the backend and the dev file which runs the MySQL and Ngrok containers). In production, we will use the base file and the prod file, since we utilize AWS RDS instead of a local MySQL container on Docker.

Additionally, the command up -d runs the compose stack and detaches it. Then we trail the logs for these containers using logs -f. You can also opt to run it directly in one command like so

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

However, when you Ctrl-C or exit this shell, it will also shutdown the docker compose stack, whereas with the original commands, exiting the shell will leave the backend running in the background.

Useful Information

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

  • localhost:3000: Loopback 4 home

    • Visit this to check that the backend is indeed running

  • localhost:3000/explorer: OpenAPI spec explorer

    • Visit this to check what endpoints are available

  • localhost:4040: Ngrok tunnel URL and interface

    • Visit this to track incoming HTTP/S requests to the webhook (i.e. when an order is created you can check if Ngrok received it here)

    • For example, if this URL shows the webhook received the request, then the error likely occurs in the backend handling the request, but if the webhook never received the request, you may need to rerun the setup and ensure Ngrok is running properly

  • Uploaded files appear in the server/storage/ folder.

    • Please upload files through the web interface as an entry in the MySQL database is also created for the file. If you just drag and drop files into this folder, it will not show on the dashboard and may cause some issues.

PreviousFrontend SetupNextGuidelines

Last updated