Initial Setup

Downloading the Files

The first step to being able to view and edit the code on this project as well as run the application is to clone this repository, either by downloading the zip of the files or by using the following git command in your command line:

git clone https://github.com/dondi/GRNsight.git

Running the Application

Version Notice

As of this writing, GRNsight uses Node.js 14.21.2, but it also runs on recent versions except Node 17 due to a one-time issue regarding SSL. The following instructions assume you have Node.js installed (see Library Requirements page for download details).

Steps to make a temporary switch to a different version of node for macOS:

GRNsight may need to run on a different version of node than is used for your other projects. Follow these instructions to make a temporary switch to a different version of node.

1. Install the older version using brew:

   brew install node@version

2. After the installation, check your terminal at the end, and find this line If you need to have node@version first in your PATH, run:, then copy the echo path

   echo 'path to copy' >> ~/.zshrc

3. Save the command somewhere that whenever you need to change the version, you can use this command.

4. Run that command

   export PATH="your path to node@version"

• Notes: This is a temporary set up, so whenever you close the terminal window, it will be set back to your original node version

Specify a PATH for Windows Users

Search "Edit the system environment variables" from the Windows taskbar. From there open environment variables and edit the Path variable. Within this variable use new to add C:\Program Files\PostgresSQL\{postgres_version}\bin and C:\Program Files\PostgresSQL\{postgres_version}\lib

Dependency Installation

Before running the applications for the first time, you must first install the dependencies using npm.

Navigate to the directory that contains the GRNsight project (substitute <GRNsight folder> accordingly in the commands below) and install the project’s dependencies.

cd <GRNsight folder>
npm install

When running GRNsight on platforms other than macOS, you may see this error:

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules/nodemon/node_modules/chokidar/node_modules/fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})

As stated by the warning, this is an optional dependency, and thus is not an issue when running GRNsight.

Database setup

1. In order to run the local GRNsight application, you need to set up a local copy of the GRNsight database. Instructions are located here.

   1. After installing your local database, you will want to either add a password to your default user postgres, or create a new user or superuser with a password. This is necessary so that GRNsight can use these credentials to log in to your database to perform database calls.

      • [OPTION 1]: Adding a password to default user postgres

        1. To edit the default user postgres, in Terminal type the following (replacing with your chosen password).

            sudo -u postgres psql -c "ALTER USER postgres PASSWORD '<new-password>';"
           

      • [OPTION 2]: Creating a new user with a password

        1. To add a new user, in Terminal type the following (replacing with your chosen username and with your chosen password).

            sudo -u postgres psql -c "CREATE ROLE <username> SUPERUSER LOGIN PASSWORD '<new-password>';"
           

      • On MacOs if you receive the error in your terminal psql: FATAL: role "postgres" does not exist, then try this solution from Stack Overflow(https://stackoverflow.com/questions/15301826/psql-fatal-role-postgres-does-not-exist?page=2&tab=scoredesc#tab-top):

        • sudo -u postgres createuser -s postgres

2. After you have a local instance of the GRNsight database on your machine, you will need to configure the environment variables for GRNsight to access your database.

   1. Navigate to the top-level GRNsight directory and create a file named .env.

   2. Inside the .env file add the following lines, replacing the and with the requested information.

       EXPRESSION_DB_USERNAME =<user>
       EXPRESSION_DB_PASSWORD =<password>
      

Running GRNsight in Development Mode

0. Start the database server (to be fleshed out)

1. Navigate to the GRNsight directory and enter the following in Terminal

   cd <GRNsight folder>
   npm run start-dev
   

   • If you run into the following error:

     TypeError [ERR_INVALID_ARG_TYPE]: The "options.cwd" property must be of type string or an instance of Buffer or URL. Received function wrappedCwd
     

     ...run this command:

     npm install --save-dev [email protected]
     

   • If that causes the following error:

     Error: Cannot find module 'C:\Users\kdahlqui\Desktop\GRNsight\node_modules\parallelshell\index.js'
     

     ...delete node-options from inside the GRNsight folder and run npm install

   • If you receive a Google Analytics error, delete the node-modules folder from the GRNsight folder and run npm update

2. In a web browser, navigate to localhost:5001 to access the running local GRNsight application. This will provide you with a view of the current state of the GRNsight site as the code on your computer produces it.

• Compatibility note: On recent versions of macOS, a service called “AirPlay Receiver” has been added which happens to use port 5000, the same port used by the GRNsight local dev server. As such, in order to allow the local dev server to run, “AirPlay Receiver” needs to be disabled in System Preferences > Sharing while GRNsight development is taking place

Reuse Commands

There are some commands that you only need to use once, but there are also commands that you have to use it every time you run it.

• Change the version of npm: export PATH="your path to node@version"

• Running GRNsight in developed mode

  cd <GRNsight folder>
  npm run start-dev
  

• Starting the database: pg_ctl start -D location-of-cluster

• Stopping the database: pg_ctl stop -D location-of-cluster