Server Setup
The production GRNsight server runs multiple processes, each accessed by the main GRNsight website (http://dondi.github.io/GRNsight) in specific contexts. These contexts are:
- production: The most recent stable version of GRNsight
- beta: The branch of GRNsight on which development is taking place
For each version of GRNsight, two processes are then needed:
- server: This is the process that accepts GRNmap spreadsheets and parses them into JSON objects for visualization by GRNsight; this process also interacts with Google Analytics to track site activity
- web-client: This is the process that delivers the GRNsight user interface
Thus, the GRNsight server runs a total of four processes: production server, production web-client, beta server, and beta web-client.
In all, the beta server includes all of the current changes and updates produced by your team before it has been pushed to the current official version of GRNsight.
This document describes how the production GRNsight server is set up to run these four processes concurrently.
NOTE: The following instructions are not necessary to the initial setup of GRNsight on your machine. Once your team feels the code is running properly and you are all ready to update the current proto-version of GRNsight, only then will you need to worry about refreshing the beta server with the new version of the code.
Currently, screen is used for running the GRNsight processes. This lets the processes run “headless” while still keeping their console output available. To run the processes:
Clone the GitHub repository for GRNsight twice: once for the production deployment and another for the beta deployment. The clones should be given distinct destination directory names so you can tell them apart.
$ git clone https://github.com/dondi/GRNsight.git GRNsight-production
$ git clone https://github.com/dondi/GRNsight.git GRNsight-beta
For the clone that will run the beta version of GRNsight, make sure to checkout the beta branch.
$ cd GRNsight-beta
$ git checkout beta
Follow the installation instructions in https://github.com/dondi/GRNsight/wiki/Running-the-Applications to get each clone ready.
The GRNsight production clone should also have PEM files in its directory for interacting with the GRNsight and GRNmap Google Analytics accounts. This is private data and so must be acquired from the GRNsight principal investigators.
Now that GRNsight is thoroughly served via the secure HTTPS protocol, developers must create a self-signed certificate and place it into the encryption folder located within GRNsight. Two files must be created, one with the suffix ".key" and the other with the suffix ".cert". On Linux/Mac, the command openssl req -nodes -new -x509 -keyout server.key -out server.cert will generate these two files.
The overall outline for starting each process is the same, differing in terms of directory and environment variables:
- Start
screen -
cdto the GRNsight directory - Run
npm run start-prodwith the corresponding environment variables
With this in mind, the specific instructions are as follows (using the target directories from the earlier examples).
These instructions will start both the server and web-client processes for the production deployment.
$ screen
$ cd GRNsight-production
$ NODE_ENV=production SERVICE_EMAIL=<GRNsight service email> GRNMAP_SERVICE_EMAIL=<GRNmap service email> npm run start-prod
The values of GRNsight service email and GRNmap service email are private and must be acquired from the GRNsight principal investigators.
These instructions will start both the server and web-client processes for the beta deployment.
$ screen
$ cd GRNsight-beta
$ NODE_ENV=beta SERVICE_EMAIL=<GRNsight service email> GRNMAP_SERVICE_EMAIL=<GRNmap service email> npm run start-prod
Once the processes have launched, test them by accessing the Home and Beta pages of http://dondi.github.io/GRNsight
When a new version is pushed to the GRNsight repository, the corresponding clone (production or beta) will need to be updated. To do so, complete the following steps:
-
Go to the GRNsight directory:
cd GRNsight-productionor
cd GRNsight-beta -
Pull the latest code from GitHub:
git pull -
If the updated code includes new library dependencies, install them:
npm install
The screen processes should detect the change and restart the processes accordingly. If in doubt, use screen -r (see below) in another command-line window prior to performing the git pull in order to monitor the console logs for this restart message.
If the screens were opened in the order above, the screens should be listed as follows:
beta
production
To restart the GRNsight processes, complete the following steps:
- Go to screen that contains the processes of whichever version needs to be restarted.
- Ctrl+C to stop the server (if needed).
- Push the up arrow to restart using the previous command (or retype the appropriate command from the instructions above).
The four processes can coexist because they all run on different ports. To hide these ports from the outside, the GRNsight server uses Nginx to map paths to ports:
location /server/ {
proxy_pass http://localhost:3000/;
}
location /client/ {
proxy_pass http://localhost:3001/;
}
location /beta/server/ {
proxy_pass http://grnsight.cs.lmu.edu:4000/;
}
location /beta/client/ {
proxy_pass http://grnsight.cs.lmu.edu:4001/;
}
- To start a new screen:
screen - To see a list of current screens:
screen -r - To start a particular screen:
screen -r ####- The number value corresponds to the screen id listed using
screen -r.
- The number value corresponds to the screen id listed using
- Exit a screen (while keeping the screen active):
Ctrl+A d - Exit a screen (close the screen):
Ctrl+a :quit - To see which node processes are running and who owns them:
ps aux | grep node