⚡Quick Start: Running locally w/o Docker (on MacOS or Linux)

Local setup (w/o docker)

If the dockerized approach is a no go, or you want to run things manually, these instructions should help.

Requirements

Requires Node 18.18.2+ and a recent version of postgres.

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

Install and run postgres

postgres instructions (MacOS)

1. Download and install the latest release of Postgres from https://postgresapp.com/downloads.html

2. Open Postgres and click "Initialize".

3. Click "Server Settings" and change the name to "dev".

4. Download and install Datagrip from https://www.jetbrains.com/datagrip/download/#section=mac

5. Open Datagrip and click "New Project".

6. Enter "PostgreSQL" as a new project name and click "OK".

7. Click "+" -> "Data Source" -> "PostGreSQL".

8. Enter "postgres" for the "User" field and click "OK".

postgres instructions (Linux)

• Install Postgres database in your system (version 11 or above. Link: https://www.postgresql.org/download/linux/).

• Install PostgreSQL client: sudo apt install postgresql-client

• Install PostgreSQL server: sudo apt install postgresql-server

• Steps to create a PostgreSQL database for upgrade user

  1. run sudo -u postgres psql(it will start postgress and show 'postgres#').

  2. run CREATE USER ${username} PASSWORD '${password}';

  3. run CREATE DATABASE ${DatabaseName};

  4. run GRANT ALL on DATABASE ${DatabaseName} to {username};

  5. run ALTER USER {username} with Superuser;

  6. run CREATE extension "uuid-ossp";

  7. \q to exit

• Download and install Datagrip from https://www.jetbrains.com/datagrip/download/#section=linux

• Open Datagrip and click "New Project".

• Enter "PostgreSQL" as a new project name and click "OK".

• Click "+" -> "Data Source" -> "PostGreSQL".

• Enter "postgres" for the "User" field and click "OK".

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

cd ./frontend
npm ci

Environment Setup

Backend:

Make a copy of env.example

cd ./UpGrade/backend/packages/Upgrade

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

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 ./UpGrade/frontend

# note that this one is not a dot file
cp environment.local.example.ts environment.example.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. Admin User 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.

# 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

CORS whitelist

Ensure that this line is present in you env

CORS_WHITELIST=localhost

See this page for other environment options.

Launch

Start the backend

In your Terminal window, type cd ~/UpGrade/backend/packages/Upgrade/, then run the following command: npm run dev

After a few seconds, if you open http://localhost:3030/api in your browser, you should see something like the following on the page:{"name":"A/B Testing Backend","version":"6.1.0","description":"Backend for A/B Testing Project"}

Start the frontend

In your Terminal window, type cd ~/UpGrade/frontend/, then run the following command: npm run start

After a few seconds, your default browser should automatically launch and display the login page. Or you can open http://localhost:4200 in your browser and log in with your account.

After the login, you should see the "Experiments" page with a welcome message, and two buttons to import or add an experiment.

Note:- After running both the frontend and backend, check DataGrip "{db-name} -> postgres -> public -> tables -> user" to verify whether your email has admin access.