⚡Quick Start: Running UpGrade Locally with Docker

Hello World!

Hosting the UpGrade Web Application on Your Local Computer

The docker way

Running in docker recommended for developing in local, as it will simulate production docker deployment as closely as possible (and it's the workflow we use).

It's entirely optional though to use this setup. See also how to run locally w/o Docker.

Requirements

Requires Node 18.18.2+ and Docker, obviously. Docker Desktop is recommended if you are not savvy with all of the docker commands (will only show a couple here for building the image).

UpGrade will also require Google account later in this setup in order to obtain authentication credentials from https://cloud.google.com/

Install

Get the code from https://github.com/CarnegieLearningWeb/UpGrade (monorepo contains all packages):

# https
git clone https://github.com/CarnegieLearningWeb/UpGrade.git

# ssh
git clone [e-mail]:CarnegieLearningWeb/UpGrade.git

By default you'll be checked out to the "dev" branch, which is the latest code, but unstable and meant for developers. For most users, switch to "main" for the latest stable build, "dev" is not going to be guaranteed to work.

git checkout main

Nav into root of project and run these commands to install dependencies.

npm ci

cd ./types
npm ci
npm run build
# copy this folder into the backend as well, the build will want it there
cp -R . /backend/packages/Upgrade

cd ./backend
npm ci

cd ./backend/packages/Upgrade
npm ci --legacy-peer-deps

cd ./frontend
npm ci

Environment Setup

Make a copy of env.docker.local.example

cd ./Upgrade/backend/packages/UpGrade

# note that this is a dot file may look hidden on terminal, ls -a will reveal
cp .env.docker.local.example .env.docker.local

Obtain a google client id and plunk it here (follow this guide)

GOOGLE_CLIENT_ID: xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com

This id will also need to be supplied in frontend/projects/upgrade/src/app/environments/environment.ts

Note: There is a DOMAIN env variable below this. If you want to restrict your user logins to your org's email domain, replace the value here with that domain. Otherwise, it should left blank

Note: you may as well create a .env from .env.example and follow these same steps so that you can run the backend outside the docker container when necessary.

See this page for other environment options.

Launch

To launch frontend, backend API, and postGres db in local docker container, run:

$ docker-compose -f singleContainerApp-docker-compose.yml up -d

NOTE: In docker app, ensure that "docker-compose v2" is enabled (otherwise you may see some errors about container names)

If all has worked, you will have a docker container running a local network that is linked to local ports. Any saved changes should hot reload automatically (no rebuild required).

• Visit UI at: http://localhost:4200

• Send API requests to: http://localhost:3030

• PostGres db login details can be found in .env.docker.local file. A free client to view DB is https://www.pgadmin.org/download/