# Quick Start: Running UpGrade Locally with Docker

## Hosting the UpGrade Web Application on Your Local Computer

### **The docker way:**

On **Mac** and **Windows**, these steps should take care of downloading all dependencies, including Docker, node 16.15, postGres, and all the `npm` installs.\
\
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](https://upgrade-platform.gitbook.io/upgrade-documentation/5.x/developer-guide/quick-start-running-locally-w-o-docker).\\

#### Install

* Get NIX shell to delegate some dependency magic:&#x20;

`$ sh <(curl -L` [`https://nixos.org/nix/install`](https://nixos.org/nix/install)`)`

* Get the code from <https://github.com/CarnegieLearningWeb/UpGrade> (monorepo contains all packages):&#x20;

`$ git clone git@github.com:CarnegieLearningWeb/UpGrade.git`

* nav into root of project and run these commands to install dependencies:

`$ cd Upgrade`

`$ make setup-local`

{% hint style="info" %}
NOTE: If this `make` command says `nix not found` and you are using `zsh` on mac, it may need to be manually added to PATH. OR, just try running it in `bash`
{% endhint %}

#### **Launch**

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

`$ make`

{% hint style="info" %}
NOTE: In docker app, ensure that "docker-compose v2" is enabled (otherwise you may see some errors about container names)

![](https://content.gitbook.com/content/dGWOHTy8uceob98MuUcy/blobs/hZv640lan13F9u9xdThe/image.png)
{% endhint %}

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/>\\

**Other Make commands you may enjoy**\
\
When switching between branches with updated dependencies, running through some of these steps may help reinstall and/or revive the app:\
\
`make down` will terminate running apps without destroying the docker container\
`make destroy` will terminate docker container entirely\
`make images` will rebuild docker images\
`make setup-local` will take care of installing `npm` dependencies and some other housekeeping\
`make db-dump` and `make db-restore` are useful for backing up or loading a db (you will need to specify local paths to files at top of `docker-compose.yml` file.\\

## Alternate setup (w/o docker)

If the dockerized approach is a no go, or you want to run things manually, these instructions should help (they are a bit dated, but should get you most of the way there!)&#x20;

## **macOS**

#### **Backend**

1. Make sure you have node.js installed. If not, [download here](https://nodejs.org/en/download/) and follow the installation instructions.
2. Download and install the latest release of Postgres from <https://postgresapp.com/downloads.html>
3. Open Postgres and click "Initialize".
4. Click "Server Settings" and change the name to "dev".
5. Download and install Datagrip from <https://www.jetbrains.com/datagrip/download/#section=mac>
6. Open Datagrip and click "New Project".
7. Enter "PostgreSQL" as a new project name and click "OK".
8. Click "+" -> "Data Source" ->  "PostGreSQL".
9. Enter "postgres" for the "User" field and click "OK".
10. Open the Terminal and run `node -v` to check the version of node installed on your system.
11. If the version is not `16.15.0`, run the following commands to install this version:

    `sudo npm install -g n`\
    `sudo n 16.15.0`
12. Run the following commands in the Terminal:\
    `git clone https://github.com/CarnegieLearningWeb/UpGrade.git` \
    (**Note:** If you don't have git, install it using using the command: `brew install git`)\
    `cd UpGrade/backend/packages/Upgrade`\
    `cp .env.example .env`
13. Open the ".env" file, find the "TYPEORM\_SYNCHRONIZE" variable and set it to `false`, and find the “ADMIN\_USERS” variable and add your account email address to it.
14. Open the "src/config.json" file and add your email and role under the "adminUsers" key.
15. Open your terminal and type\
    `cd ~/UpGrade/backend` \
    Run the command `npm ci` in this directory. \
    Then type `cd ~/UpGrade/backend/packages/Upgrade` \
    Run the command `npm ci` in this directory as well. (These commands are to be used only during the initial setup to install dependencies)
16. Once the above command finishes, run the following command in the "backend/packages/Upgrade" directory: `npm run dev`
17. After a few seconds, you should see a message "Aloha, your app is ready on <http://localhost:3030/api>" in the Terminal console.
18. 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":"2.0.0","description":"Backend for A/B Testing Project"}`

\
**Frontend**

1. In your Terminal window, type `cd ~/UpGrade/frontend/`\
   Then, run the following command in the Terminal: `npm ci` (This is used only during the initial setup to install dependencies)
2. Once the above command finishes, run the following command: `npm run start`
3. After a few seconds, your default browser would automatically launch and display the login page. Or you can open <http://localhost:4200> in your browser and log in with your account.
4. 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.

### Linux

#### Backend

1. Install Postgres database in your system (version 11 or above. Link: <https://www.postgresql.org/download/linux/>).
2. Install PostgreSQL client: `sudo apt install postgresql-client`
3. Install PostgreSQL server: `sudo apt install postgresql-server`
4. 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
5. Download and install Datagrip from <https://www.jetbrains.com/datagrip/download/#section=linux>
6. Open Datagrip and click "New Project".
7. Enter "PostgreSQL" as a new project name and click "OK".
8. Click "+" -> "Data Source" ->  "PostGreSQL".
9. Enter "postgres" for the "User" field and click "OK".
10. Open the Terminal and run `node -v` to check the version of node installed on your system.
11. If the version is not `16.15.0`, run the following commands to install this version:

    `sudo npm install -g n`\
    `sudo n 16.15.0`
12. Run the following commands in the Terminal:`git clone https://github.com/CarnegieLearningWeb/UpGrade.git`\
    `cd UpGrade/backend/packages/Upgrade`\
    `cp .env.example .env` **Note:** Install git if you don’t have it, using the command:&#x20;

    `sudo apt-get install git`
13. Open the ".env" file, find the "TYPEORM\_SYNCHRONIZE" variable and set it to `false`, and find the “ADMIN\_USERS” variable and add your account email address to it.
14. Open your terminal and change your directory to "backend" once  and also to "backend/packages/Upgrade" directory. Run the following command in both: `npm ci` (To be used only during the first setup time to install the dependencies)
15. Once the above command finishes, run the following command in "backend/packages/Upgrade" directory: `npm run dev`
16. After a few seconds, you should see a message "Aloha, your app is ready on <http://localhost:3030/api>" in the Terminal console.
17. 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":"2.0.0","description":"Backend for A/B Testing Project"}`

#### Frontend

1. In your Terminal window, type `cd ~/UpGrade/frontend/` and run the following command in the Terminal: `npm ci` (To be used only during the first setup time to install the dependencies)
2. Once the above command finishes, run the following command: `npm run start`
3. After a few seconds, your default browser would automatically launch and display the login page. Or you can open <http://localhost:4200> in your browser and log in with your account.
4. 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.
