Pathway Commons App(s)

Required software

• Node.js >=10.0.0 <11.0.0

Running the App Locally

1. Install the project dependencies by typing:

   npm install
   

2. Run the project using one of the defined package scripts:

   For development:

   npm run watch
   

   For a production build:

   npm run build-prod
   npm start
   

Configuration

The following environment variables can be used to configure the server (also docker image):

• NODE_ENV: the environment mode, either production or development (default)
• PORT: the port on which the server runs (default 3000)
• PC_URL: Pathway Commons homepage URL (default: 'http://www.pathwaycommons.org/'; cPath2 service should be there available at /pc2/ path)
• NCBI_API_KEY: NCBI E-Utilities API key (read more)
• FACTOID_URL: the Factoid app URL (default: 'https://biofactoid.org/')
• SBGN_IMG_SERVICE_BASE_URL: URL for service that converts SBGN to an image (i.e. Syblars; default is http://localhost:9090/)
• SBGN_IMG_PATH: cli tool snapshot output folder for images (default: public/img/pathways)

Run targets

• npm start : start the server
• npm stop : stop the server
• npm run build : build project
• npm run build-prod : build the project for production
• npm run bundle-profile : visualise the bundle dependencies
• npm run clean : clean the project
• npm run watch : watch mode (debug mode enabled, autorebuild, autoreload)
• npm test : run tests
• npm run lint : lint the project
• npm run ci : run the tests and lint and build-prod at once

Using Docker and Dockerfile

Build the image.

docker build -t pathwaycommons/app-ui .

Run the container:

docker run --detach --rm --publish 3000:3000 --env "NODE_ENV=production" --name "app-ui" pathwaycommons/app-ui

Testing

All files /test will be run by Mocha. You can npm test to run all tests, or you can run npm run test ./test/path/to/test to run specific tests.

Chai is included to make the tests easier to read and write.

Scripts

Command line tools

The scripts/cli.js file contains app-ui command line tools:

• source: Download and extract a file to downloads folder
• snapshot: Generate PNG images for pathways listed in a PC GMT-formatted file
  • Requires an instance of Syblars accessible at a location defined by the configuration variable SBGN_IMG_SERVICE_BASE_URL
  • Images will be placed in directory SBGN_IMG_PATH (default: public/img/pathways)

Generate image snapshots from a GMT file

1. Retrieve a GMT file

   Pathway Commons makes compressed archives of GMT files for each release available for download. For PC version 14, issue the following command:

   node src/scripts/cli.js source --file pc-hgnc.gmt https://download.baderlab.org/PathwayCommons/PC2/v14/pc-hgnc.gmt.gz

2. Build and run a Syblars instance

   docker build --file Dockerfile.syblars -t pathwaycommon/syblars:latest .
   docker run --detach --rm --publish 9090:3000 --name syblars pathwaycommon/syblars:latest

3. Generate a PNG of an SBGN representation for each pathway declared in the GMT file at downloads/pc-hgnc.gmt:

   SERVER_FETCH_TIMEOUT="60000" node src/scripts/cli.js snapshot --file pc-hgnc.gmt

• Notes
  • The default timeout of fetch is normally quite brief (5 seconds).
  • Images will be served via expressJS at img/pathways/:id, where id is the pathway URI with anything that is not a letter (a-z) or digit (0-9) is replaced with underscores (_).

Developing a feature and making a pull request

Students who work on the repo should follow these instructions for each feature that they work on:

1. Initial preparation (only needed once)
   1. Make a fork on GitHub (if you haven't already) under your personal account
   2. Check out the fork repo: git clone https://github.com/myusername/app-ui.git
   3. Change the directory to the project: cd app-ui
   4. Check out the development branch: git checkout -b development origin/development
   5. Add the pc remote: git remote add pc https://github.com/PathwayCommons/app-ui.git
2. Make sure you have the latest code on the main PathwayCommons repo:
   1. Using the console: git fetch pc
   2. Or using GitUp: Remotes > Fetch All Branches, Remotes > Fetch All Tags
3. Make sure your development branch is up-to-date:
   1. Using the console: git checkout development && git merge pc/development
   2. Using GitUp:
      1. Right-click the commit that pc/development points to
      2. Select Merge into Current Branch
4. Make a feature branch for the new feature or change you are working on. Make sure to give your branch a clear, meaningful name.
   1. Using the console: git checkout -b name-of-feature
   2. Using GitUp: right-click the HEAD commit (which should be the top commit of your local development branch), then select Create Branch...
5. Make commits as you're working on your feature:
   1. Using the console: git commit -am "My descriptive commit message"
   2. Using GitUp: Use the Select View tab (View > Commit)
      1. Stage the files
      2. Add a descriptive commit message
      3. Press the Commit button
6. Periodically (at least once just before making a pull request) make sure your feature branch takes into account the latest changes other people have made:
   1. Make sure your development branch is up-to-date:
      1. Using the console: git checkout development && git merge pc/development
      2. Using GitUp:
         1. Right-click the commit that pc/development points to
         2. Select `Merge into Current Branch
   2. Make sure your feature branch is up-to-date:
      1. Using the console: git checkout name-of-feature, git merge development
      2. Using GitUp:
         1. Make sure your HEAD is the newest commit of your feature branch: Right-click the latest commit on name-of-feature branch and select Checkout "name-of-feature" Branch
         2. Right-click the latest commit of the development branch and select Merge into Current Branch
7. Push your commits to GitHub:
   1. Note: You can push as often as you'd like so that your code is backed up on GitHub. You must push everything before you make a pull request.
   2. Using the console: git push
   3. Using GitUp: Remotes > Push Current Branch
8. When your feature is done and ready to be reviewed, make a pull request:
   1. Go to your fork on GitHub, e.g. https://github.com/myusername/app-ui
   2. Select your feature branch
   3. Click the New pull request button
   4. Give your pull request a clear title and a meaningful description

Publishing a release

1. Create a release branch off of master, e.g. release/1.2.3
2. Merge the latest dev into the release branch.
3. Make sure the tests are passing: npm test
4. Make sure the linting is passing: npm run lint
5. Bump the version number with npm version, in accordance with semver. The version command in npm updates both package.json and git tags, but note that it uses a v prefix on the tags (e.g. v1.2.3).
6. For a bug fix / patch release, run npm version patch.
7. For a new feature release, run npm version minor.
8. For a breaking API change, run npm version major.
9. For a specific version number (e.g. 1.2.3), run npm version 1.2.3.
10. Make a PR for the release branch onto master.
11. Push the release: git push origin --tags
12. Publish a release for Zenodo.