⚡Quick Start: Running UpGrade Locally with Docker

Hello World!

Hosting the UpGrade Web Application on Your Local Computer

The docker way

Running in docker is 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 UpGrade

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 ./packages/Upgrade
npm ci

cd ../../../frontend
npm ci

Environment Setup

Backend:

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

Admin user

# modify this line, note the syntax for adding multiple users and roles
ADMIN_USERS=user@email:admin/\user2@email:admin

# add yourself
ADMIN_USERS=you@yourcompany:admin

UpGrade will start up with certain users automatically added as admin roles. You will want to put your email address in so that after login, you will have all permissions for your user in the UI. You will know if this is set correctly if you are able to see the "Add Experiment" and "Import Experiment" buttons on startup. If they are missing, it means you are a "reader" role, check this env var.

CORS whitelist

Ensure that this line is present in your env

CORS_WHITELIST=localhost

Google Client Id: 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 be left blank. See other backend env option documentation here. Frontend: Make a copy of environment.local.example.ts

cd ../../../frontend/projects/upgrade/src/environments

# note that this one is not a dot file
cp environment.local.example.ts environment.local.ts

Put the google client id from about into the field: `googleClientId`

googleClientId: xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com

See other frontend env option documentation here.

See this page for other environment options.

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.

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/