⚡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
Download and install the latest release of Postgres from https://postgresapp.com/downloads.html
Open Postgres and click "Initialize".
Click "Server Settings" and change the name to "dev".
Download and install Datagrip from https://www.jetbrains.com/datagrip/download/#section=mac
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 Postgres database in your system (version 11 or above. Link: https://www.postgresql.org/download/linux/).
Install PostgreSQL client:
sudo apt install postgresql-clientInstall PostgreSQL server:
sudo apt install postgresql-serverSteps to create a PostgreSQL database for upgrade user
run
sudo -u postgres psql(it will start postgress and show 'postgres#').run
CREATE USER ${username} PASSWORD '${password}';run
CREATE DATABASE ${DatabaseName};run
GRANT ALL on DATABASE ${DatabaseName} to {username};run
ALTER USER {username} with Superuser;run
CREATE extension "uuid-ossp";\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 git@github.com:CarnegieLearningWeb/UpGrade.gitBy 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 mainNav 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 ciEnvironment 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 .envAdmin 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:adminUpGrade 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=localhostGoogle Client Id: Obtain a google client id and plunk it here (follow this guide)
GOOGLE_CLIENT_ID: xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.comThis 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.tsPut the google client id from about into the field: `googleClientId`
googleClientId: xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.comSee other frontend env option documentation here.
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.
Last updated