pathwaycommons/app-ui repository overview

⁠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
   

   Copy

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

   For development:

   npm run watch
   

   Copy

   For a production build:

   npm run build-prod
   npm start
   

   Copy

⁠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
   

   Copy

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
   

   Copy

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
   

   Copy

• 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.