Getting Started with Development

This guide assumes you are familiar with Node.js, git, ssh keys, and the command line. If not, please speak to a project manager to assist you.

You will need the following installed:

• Git
• Node.js version 9.11.1 & npm
• MongoDB - the database
• babel-node
• (optional) Compass - used for visualizing MongoDB collections
• (optional) An AWS account. You'll need to generate an access key ID and secret key. This is required for saving images and sending emails. For emails you'll also have to verify a couple email addresses for testing.
• (optional) pm2 - the repository installs it locally so it can be run with npx, but if you install it globally you can skip the npx portion of the command.

1. Clone The Repositories

git clone git@github.com:phylogeny-explorer/explorer.git

Verify that the addresses are set properly in the front end. Edit the file client/webpack.config.js and modify the following code:

'PUBLIC_API_HOSTNAME' : '"localhost:5500"',
'ADMIN_API_HOSTNAME'  : '"localhost:5000"',
'WEBSITE_HOSTNAME'    : '"localhost:3000"',

(The port numbers are specified in step 4.)

2. Install

Run the following command to install the dependencies and tools for the project:

npm install

3. Copy the Database

Make sure you have mongodb installed and the daemon/service is running.

Optionally, you can run mongo via docker using command docker run -d -p 27017:27017 mongo

There is a built-in admin user that can be used for testing with the username/password admin/adminadmin.

From a directory called dump. Run the following commands to import data into mongodb locally:

mongoimport -d phylex-admin users.json

mongoimport -d phylex-admin roles.json

mongoimport -d phylex-public -c clades clades.json

4. Building

The repository- contains source code that's written in ES6. Node.js and browsers do not support ES6, so before the server can be started, or the code run in a browser, the source code must be built. Fortunately, this system is already in place and can be done using one of two commands:

Single Build

Target Directory: ./build

npm run build

Used to create a single build of the project. This will run the code through babel and output the resulting server and front-end (if applicable). A node process manager (see The Process Ecosystem section below) can be used to start the node server using the server.js file generated by this build.

Continuous Build

This is currently not working.

Target Directory: ./build

npm run build:watch

Same as the Single Build, but rebuilds any time there are changes to the project source.  A node process manager can be used to start the node server using the server.js file generated by this build. Running the process manager in watch mode will cause the server to restart any time changes are made to the project source.

5. Optional: Setup Amazon Email & Templates

In order to be able to send emails from the app, you need to set up a couple things.

First you need to sign up with Amazon Web Services in order to get an identity to be used by the the Amazon Simple Email Service (SES).

Second you have to copy the access key and secret key and put them in two different places:

1. Inside the ecosystem.config.js file above, for environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY near the top.
2. In your system environment variables in order to upload email templates, see below.

Next step is to run a script to upload the email templates used by the system. There are a number of templates, located in folder common/aws/ses/templates/*.js. When you want to upload them, run the following commands, but configure the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY beforehand:

export AWS_BUCKET=phylex-assets
export AWS_REGION=us-east-1
export AWS_IDENTITY_POOL_ID=
export AWS_ACCESS_KEY_ID=<your access key goes here>
export AWS_SECRET_ACCESS_KEY=<your secret key goes here>
cd common
npx babel-node aws/ses/AddTemplate.js new-user password-reset registration-accepted user-registration

Also you should edit your ecosystem.config.js (see step 6 below) to modify the AWS_SENDER_EMAIL variable and make it your own email account in order to receive administration emails.

6. The Process Ecosystem and Manager

The PM2 program is used to run your node apps. It is very powerful and can do much more than what is listed here, so it is recommended that you read into the documentation to see all of the neat things it can do.

PM2 uses configuration files to determine what to run. There is an example file provided in the repository called ecosystem.config.js. You may need to customize this file based on your own setup, so be sure to inspect and understand it.

With the ecosystem file in place, you can go into your workspace and run the following command. This will start up the client, user-api, tree-api, and daemon apps - all of which are required to run the Explorer - in "watch" mode; meaning, any time the project is built, the process will restart so that you can refresh and see your changes without having to manually restart the app each time. 

npx pm2 start ecosystem.config.js

You should now be able to access http://localhost:3000 and see the explorer running. Note that if you make a change in the code, you'll have to rebuild with npm run build unless you are running it in watch mode.

To stop all the apps using pm2, type:

npx pm2 stop ecosystem.config.js

BrowserSync Front-End Development

This section is out of date and no longer works. It will be updated when this process is fixed.

When developing the front end, you might want to run the program with BrowserSync which will update most of your changes in real time, without having to refresh the page. When you do that, you can't run the front end using pm2 at the same time. So you should first stop all pm2 apps as per the last section, and then comment out the "client" section in ecosystem.config.js. Then, run pm2 again. Once all the back-end services are running, run this in the client directory:

npm run start

7. Monitoring and logs

While running in pm2, you can look at the log files by typing this command: 

npx pm2 log --lines 100

You can also open an interactive monitoring application by running:

npx pm2 monit

If you're running with npm (to use BrowserSync) you can see the log file in the console where you executed the command.

Optional: Eclipse IDE

You can use Eclipse along with the Nodeclipse plugin to edit Node.JS projects.

After you've installed those things, you can install the nodeclipse module and import the project into Eclipse.

And that's it! You should be all set up! Happy programming!