# Setting up Truman locally

The following steps will guide you through how to set up your own version of The Truman Platform. At the end, you should have a running version of the project on your local computer.

Below is a brief overview of the steps you will take to set up Truman locally: 

1. [Creating a MongoDB database instance ](#creating-a-mongodb-database-instance)
2. [Downloading the code from GitHub](#downloading-the-code-from-github)
3. [Setting up Truman](#setting-up-truman)

The instructions for each step are outlined below. 

***

## Creating a MongoDB database instance

The Truman Platform uses MongoDB as its database system. It is where participant data, simulation data, and more is stored.

MongoDB Atlas is a managed cloud database service that hosts MongoDB databases. We will be using MongoDB Atlas to easily set up a free MongoDB database.

### Step 1: Create an account on MongoDB Atlas

1. Go to <https://www.mongodb.com/atlas/database>.&#x20;
2. Click the green **Try Free** button in the top right of the header.&#x20;
3. Sign up for an account by filling in your new account information and then clicking the **Create your Atlas account** button. After verifying your account, sign into your new account.
4. Upon signing in, you should be directed to the **Database Deployments** page.&#x20;

### **Step 2: Create a MongoDB database**

1. Click the green **Build a Database** button. You will be redirected to a selection page.&#x20;

   1. Choose the free database available.
   2. Choose AWS as the provider.
   3. Choose a region within the United States (ex: 'N. Virginia (us-east-1)').&#x20;
   4. Give your Cluster a name (ex: 'truman'; the default is 'Cluster0').
   5. You do not need to change any of the other selected default options.
   6. Click on the green **Create** button.

   <figure><img src="https://797468930-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOR396HK0xjvBHL78w6Qi%2Fuploads%2F1LsZ8tBj9HQOE1pzTmNW%2Fimage.png?alt=media&#x26;token=b24166f7-9783-47fb-900c-54eec8f02297" alt=""><figcaption></figcaption></figure>

2. Wait for a while as your cluster is created (might take 5-8 minutes).

3. After the cluster is created, you will be redirected to the **Security Quickstart** page. Instead of defining Database Access and Network Access here, we will do it another way.

4. First, create a new MongoDB user.&#x20;

   1. Navigate to **Security** > **Database Access** via the left navigation panel.&#x20;
   2. Click the green **Add a New Database User** button.&#x20;
   3. Choose the authentication method: **Password**.
   4. Under Password Authentication, create a username and password for the MongoDB User. You will need to remember both of these values.
   5. Under **Database User Privileges**, choose the built in role: **Atlas Admin**.
   6. You do not need to complete or select anything else. Click the green **Add User** button.

   <figure><img src="https://lh6.googleusercontent.com/g-aj9jBadnVeuWX6P-YTHM3SsBKYJ8Xzoyz-pARXrnSs7BKTG22moLu_hgfg7fx4Qw6QQ12e8x9_qa0LL2wcDFIdVgjeQ8LA7hkhLX1BA_TJxOvAdtfxNdg6rcSBtWlt-HSZj613ijPio5El63Lg0wo" alt=""><figcaption></figcaption></figure>

5. Afterwards, you will set up Network Access to your database.

   1. Navigate to **Security** > **Network Access** via the left navigation panel.&#x20;
   2. Click the green **Add IP Address** button.&#x20;
   3. Click **Allow Access from Anywhere**. This will add 0.0.0.0/0 to the field **Access List Entry**. Click **Confirm** to save the 0.0.0.0/0 whitelist.

   <figure><img src="https://lh4.googleusercontent.com/m1VeYDN_BoJRKbhd-F2bGhiUJyMokOzzerX67DsJpRAZL2TIuJNZ6XI33AGYvPhoUGc0gLOwBSbZE_86y-JGKWguautKn9CNZKWp5-QvWg594Q2o0WxuxjP1fVpUj_jN_r0yQi58AOvaj33ElIKk0Do" alt="" width="563"><figcaption></figcaption></figure>

6. Afterwards, navigate to the Clusters page by clicking **Deployment** > **Database** via the left navigation panel.&#x20;

   \
   Then, click on the **Connect** button under the name of your cluster (the default name was Cluster0, if you did not change it). A screen should then appear.

<figure><img src="https://lh4.googleusercontent.com/bo9jg3Q_HFUKBx2X7L4cGnpGyyJJPNxxhp6l55EeJ2zZHTQ_pNyk7lNOfYj0_tS-NWvPmKcx41WKk7fPcCrCsTse9BpmCxB0EeTBtglzpL0rrllm8rT8-5tYk_BpApDp1UmVKCZ9dsfDHTH5A7G3hUs" alt=""><figcaption></figcaption></figure>

7. Under **Connect Your Application**, choose the connection security **Drivers**.
8. In the new screen:&#x20;

   1. Select **Node.js** as the Driver and Version **5.5 or later** in Step 1.
   2. Ignore Step 2.&#x20;
   3. Copy the URL Connection String in Step 3. Then:&#x20;
      1. Replace *\<password>* in this connection string with the password you used when creating the MongoDB user in Step 4 earlier (hint: replace ALL of \<password>, including the < and > with the value of your password).&#x20;
      2. Between the backslash ('/') and question mark ('?'), insert the name of your cluster (the default name was Cluster0, if you did not change it).
      3. Keep this URL Connection String handy (record it somewhere, but do not share it online) as you will use it later in your application code to connect Truman to this database.

   <figure><img src="https://797468930-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOR396HK0xjvBHL78w6Qi%2Fuploads%2FUaFGehekcCVNnFY7CZxG%2Fimage.png?alt=media&#x26;token=0bbeb183-0cfa-4fcd-b76e-dcc79ee25faf" alt="" width="561"><figcaption></figcaption></figure>
9. (optional) Download [MongoDB Compass](https://www.mongodb.com/products/tools/compass)
   1. MongoDB Compass is the GUI for MongoDB. It is a free interactive tool that lets you easily see the objects/data in the database. It is also helpful for querying, optimizing, and analyzing MongoDB data.&#x20;
   2. This is an optional step only if you want to easily see the objects in the database, which is helpful for testing purposes (you can skip this step if you  would like).&#x20;

## Downloading the code from GitHub

The most recent codebase for The Truman Platform can be found here: <https://github.com/cornellsocialmedialab/truman_2023>.&#x20;

This repository contains the most recent code (last updated in September 2023), which includes a variety of updates since the original project (which was created in 2019). We recommend using this repository.&#x20;

However, if you would like to use the original project repository, you can find it here: <https://github.com/cornellsml/truman>.&#x20;

### **Step 1: Create your own Truman repository (codebase) using the most recent codebase**

You will use the Truman codebase as a template to create your own code repository of Truman. This allows you to create your own projects without affecting the main Truman source code.

1. Go to [GitHub](https://github.com/), and sign into your account.&#x20;
2. Then, go to <https://github.com/cornellsocialmedialab/truman_2023>.&#x20;
3. Click the green button that says **Use This Template**. Then, click **Create a new repository**.

<div align="center" data-full-width="false"><figure><img src="https://797468930-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOR396HK0xjvBHL78w6Qi%2Fuploads%2FVfQiHcN3EK8GC8frm7tz%2Fimage.png?alt=media&#x26;token=1ba7b9db-eda4-4edc-a888-1836aab1127f" alt=""><figcaption></figcaption></figure></div>

4. You should be redirected to a new page with a form to create a new repository. Complete this form:
   1. Give your repository a name (for example: "truman-socialnormsproject").
   2. Set a description for your repository (optional).&#x20;
   3. Select the "Public" option to make your repository public.&#x20;
   4. Click **Create repository**.

<figure><img src="https://797468930-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOR396HK0xjvBHL78w6Qi%2Fuploads%2FndndQAe3p1k1Xt1erGBv%2Fimage.png?alt=media&#x26;token=5994b0b5-a2cf-4182-b4fa-ae01d04caf04" alt=""><figcaption></figcaption></figure>

You now have your own version of Truman on your own GitHub account!

### **Step 2: Cloning your Truman project onto your local computer**

Now that you have a version of Truman on your own GitHub account, clone this codebase onto your local machine. Cloning creates a local copy of the code on your own laptop.&#x20;

Having a local copy of the code on your laptop allows you to make changes to the code and test and observe them locally before pushing them publicly to the repository or for deployment.

1. For instructions on how to clone your repository, see [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).<br>

   You can either use (1) the terminal/command prompt (as seen in the above instructions) or (2) the GitHub Desktop application, which you downloaded earlier (see [here](https://help.github.com/en/desktop/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop) for instructions on how). \
   \
   If you are unfamiliar with using the terminal/command prompt, we recommend using the GitHub Desktop application.<br>
2. Be sure to remember which file directory you cloned the repository to on your local computer.

## Setting up Truman

Now that you have a local copy of the Truman codebase on your own laptop, we will complete some steps and configuration to get it running.&#x20;

### Step 1: Install the project package dependencies&#x20;

1. Open the terminal/command prompt.&#x20;
2. `cd` (change directory) into the file directory you cloned the repository to by entering the command `cd <file-directory-path>` and replacing \<file-directory-path> with the file directory path. \
   \
   For example, if you cloned the repository into C:\Users\JohnDoe\Documents\GitHub\truman you would enter `cd C:\Users\JohnDoe\Documents\GitHub\truman` in the terminal/command prompt.&#x20;
3. Next, enter `npm install` in the terminal/command prompt. This installs all the external node libraries for Truman . You are going to see a bunch of lines of code come and go on the screen. This is completely normal. This may take a few minutes as the project needs to download and install a lot of libraries. Afterwards, you should see a screen similar to the one below, with a message like “added XXXX packages….”, indicating the installation was successful. \
   \
   Note: If the installation prompts you to update npm, you can update npm. However, it is not necessary.<br>

   <figure><img src="https://797468930-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOR396HK0xjvBHL78w6Qi%2Fuploads%2F6VSylWT008LkDNQZ939v%2Fimage.png?alt=media&#x26;token=1f1fe488-4d04-42fe-af6e-7bb78b9376ec" alt=""><figcaption></figcaption></figure>

### Step 2: Create and edit the environment file (.env)&#x20;

The purpose of the **.env** (environment) file is to locally store environment-specific variables (with the format KEY=VALUE) on the machine rather than on the cloud server. This is important for sensitive information such as the MongoDB connection string, since we don't want to be visible to the public or else others could have access to the database.

An example **.env** file is provided in the codebase (**.env.example**) to help you create this .env file. You will now create the **.env** file and add the MongoDB URL connection string that you saved earlier. This will connect your project with the database you created earlier.

1. Copy the **.env.example** file:&#x20;

{% tabs %}
{% tab title="Mac" %}

1. Enter the following command in the terminal (in the file directory of your project):\
   `cp .env.example .env`\
   This creates a copy of the file **.env.example** to **.env**.
2. You should now have a **.env** file, with all the environment variables in the .env.example copied over.
   {% endtab %}

{% tab title="Windows" %}

1. Enter the following command in the command prompt (in the file directory of your project):\
   `copy .env.example .env`\
   This creates a copy of the file **.env.example** to **.env.**
2. You should now have a **.env** file, with all the environment variables in the .env.example copied over.
   {% endtab %}
   {% endtabs %}

{% hint style="warning" %}
**NOTE:** DO NOT copy the **.env.example** file by copying, pasting, and renaming the file in the File Directory/Explorer. You will encounter errors if you do this.
{% endhint %}

2. Update the environment variables (specifically the MongoDB URL connection string) in your newly created **.env** file:&#x20;

{% tabs %}
{% tab title="Mac" %}

1. Edit the .env file with nano by entering `nano .env` in the terminal.&#x20;
2. Replace the value of the key **MONGODB\_URI=** with the URL that you recorded down earlier to tell the application which database to connect to (i.e. replace the value to the right of the equals signs with the connection string; see the screenshot below as an example). Make sure that there are no spaces between the key and the connection string.
3. Exit the nano window with **CTRL+X.**&#x20;
4. Before exiting, you will be asked if you want to save your changes to the file. Press **Y** and hit **Enter** to save.&#x20;
5. Next, you will be asked to give the file a name. You do not need to give the file a new name, so simply hit **Enter** again.
   {% endtab %}

{% tab title="Windows" %}

1. Edit the .env file with a text editor by entering `.env` in the command prompt. This should open the file in a text editor.
2. Replace the value for the key **MONGODB\_URI=** with the URL that you recorded down earlier to tell the application which database to connect to. Make sure that there are no spaces between the variable and the connection string. (See screenshot below).
3. Then save the file.&#x20;
   {% endtab %}
   {% endtabs %}

<figure><img src="https://797468930-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOR396HK0xjvBHL78w6Qi%2Fuploads%2F9FkGKT4hHaOOQe42S0gX%2Fimage.png?alt=media&#x26;token=c027824c-80c8-4a12-a55a-b944fcd510e7" alt=""><figcaption></figcaption></figure>

### Step 3: Populate your database

Now that you have indicated in your project which database to connect to, it is time to populate the database with the simulation content.&#x20;

1. Enter `node populate.js` in the terminal/command prompt.\
   This command runs the script **populate.js**, which connects to the MongoDB database you just defined in the **.env** file and uploads the simulation data found in the csv files in the **./input** folder in the project directory to the MongoDB database you created.&#x20;
2. You should see something printed similar to this.

<figure><img src="https://lh4.googleusercontent.com/vIY4TGbqDkPK4wZArMZNCp9bkhPDQ-CJgn0xQMSxAYs6Bz9ofzYyKmjUB-lEKAXUp5eHZ3YB6l6EhXJzD2FIccIWx7sQKPR58-3zG7iusstCR9z3iKe3Frz_V_osrw5c2modK3jwakPPeXQ1HSySR24" alt="" width="563"><figcaption></figcaption></figure>

3. After the script is done running, go to <https://cloud.mongodb.com/> to look at the database you just populated.
   1. Click **Database > Clusters** via the left navigation panel.
   2. Click on the name of your cluster (the default name was Cluster0, if you did not change it).
   3. Under Collections, you should now see 3 new collections in your database, called “actors”, “scripts”, “notifications”. These are the objects that form the simulation (actors, posts, comments, notifications etc.)&#x20;

<figure><img src="https://lh3.googleusercontent.com/HjFo0Vf_j_xkbxVtX_bcIkH-UJlNDFufE8dEBoNtRqE-u95wJ8tZYjjghX4j7b3KvNf0YSfrZcjQkQBBGhzRO25838c6nXJKOw9GKpTSR2HmE-P8eHVQveenRb1jY45tKJYhaKqN3ob32Xn-3htkaEE" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note: If you downloaded MongoDB Compass earlier (an optional step), you can also view your database via MongoDB Compass. This may be an easier interface to use than the web browser interface if you plan to manipulate and check the objects in your database often:\
\
Open MongoDB Compass on your local machine. When it prompts you to enter a connection string, enter your MongoDB Connection String and click **Connect**. You should then see a very similar interface as the picture above.
{% endhint %}

## Using Truman for the first time!

1. Now that everything is installed, we can now run Truman on your local device! Enter `npm run dev` in the terminal/command prompt. This starts your server.
2. Then, go to **<http://localhost:3000/>** in the browser of your choice.
3. You should be able to see a screen like the one below.&#x20;
4. Congratulations! You now have your own version of Truman running on your local computer! Create a new account and try out Truman for yourself.

   <figure><img src="https://lh5.googleusercontent.com/w3lyT2OTZ0DL9bIWF3aowRtByQbAOt-QVCreapT1a4-ZgrODO236BT-e2heskfOpho9CWRh2s6e_j0AqR45w1NM7bnxPPLZ9KxTJXi0spn29e7gA59z6ToxA_AFXwj4o5y-fgi8RwKHCKGypcPWD6is" alt=""><figcaption></figcaption></figure>