Guide to running portal locally with a custom portal config

This guide shows you how to test a portal config (aka gitops.json file) locally, so that you don't have to wait until the new gitops.json file is uploaded to GitHub and merged to see if your changes will break everything!

Assuming you want to edit the gitops.json file for gen3-riphl-dev-tgeg-fd.azurefd.net:

(Before you start make sure that gen3-riphl-dev-tgeg-fd.azurefd.net is up and running!)

1. Make sure that you have git https://git-scm.com/book/en/v2/Getting-Started-Installing-Git, node.js and npm https://www.npmjs.com/get-npm all installed.

   1. To test if npm and node are working: open a terminal window and type npm -v. If you see something like 4.2.0 you're good, if you see something like command not found: npm and you're sure you installed Node and npm, you may need to restart your terminal for it to work, or you could have a problem with your path: https://stackoverflow.com/questions/27864040/fixing-npm-path-in-windows-8-and-10.

2. Download the cdis-manifest GitHub repo, type:

   git clone https://github.com/bioteam/cdis-manifest.git

   You should see this message after you hit enter:

   Cloning into 'cdis-manifest'...
   remote: Enumerating objects: 160, done.
   remote: Counting objects: 100% (160/160), done.
   remote: Compressing objects: 100% (118/118), done.
   remote: Total 11019 (delta 86), reused 66 (delta 31), pack-reused 10859
   Receiving objects: 100% (11019/11019), 23.81 MiB | 11.82 MiB/s, done.
   Resolving deltas: 100% (6924/6924), done.
   

3. Download the data-portal github repo to the same folder.

   git clone https://github.com/uc-cdis/data-portal

4. Revert to 2020-09 tagged release.

   git checkout tags/2020.09 -b 2020.09

5. Now navigate to the data-portal folder (cd data-portal) and run npm install --loglevel verbose. This command will probably take a few mins.

   1. There may be some errors that show up — if they look like this: [email protected] requires a peer of react@>=16.9.0 but none is installed. You must install peer dependencies yourself. then that's ok

6. Once the npm install command finishes, follow these instructions to run portal locally: https://github.com/uc-cdis/data-portal#local-development-and-devhtml. Here's a tl;dr version:

   1. In the terminal, in the data-portal folder, type HOSTNAME=gen3-riphl-dev-tgeg-fd.azurefd.net NODE_ENV=auto bash ./runWebpack.sh. This will start the local version of portal, it could take a minute or two to compile. Once you see a message that says: ℹ ｢wdm｣: Compiled with warnings.you're good!
   2. Open a browser and go to https://localhost:9443/bundle.jsand accept the warning about certificates. (May be hidden under a small button saying advanced.) If it works, you should see a bunch of code appear. You should only need to do this once every few weeks.
   3. Go to https://gen3-riphl-dev-tgeg-fd.azurefd.net/dev.html. You should see the good old RIPHL-DEV page — but this one is coming from INSIDE the computer!
   4. Now, go back to your terminal and hit Ctrl+C to cancel your local portal. This should stop the runWebpack.sh job that's been running. We'll start it again soon.

7. Now, if you edit the cdis-manifest/gen3-riphl-dev-tgeg-fd.azurefd.net/portal/gitops.json file and save it, and then go back and run step 6 again, your local copy of portal will run with the edited version of the gitops.json file. So if you e.g. tweak the Discovery page config in your local version of gitops.json and then restart your local portal using step 6, you'll see your changes when you go to https://gen3-riphl-dev-tgeg-fd.azurefd.net/dev.html.

   1. If you see an error like this when you try to start your local portal again, this means that another local portal is still running! Make sure you cancel (Ctrl+C) any other HOSTNAME=gen3-riphl-dev-tgeg-fd.azurefd.net NODE_ENV=auto bash ./runWebpack.sh jobs that are still running.

   ✖ ｢wds｣:  Error: listen EADDRINUSE: address already in use 127.0.0.1:9443
       at Server.setupListenHandle [as _listen2] (net.js:1318:16)
       at listenInCluster (net.js:1366:12)
       at GetAddrInfoReqWrap.doListen [as callback] (net.js:1503:7)
       at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:69:8) {
     code: 'EADDRINUSE',
     errno: -48,
     syscall: 'listen',
     address: '127.0.0.1',
     port: 9443
   }
   

   1. Terminal pro tip: You can cycle through previous terminal commands with the up arrow key, or search through your terminal history with Ctrl+R (on mac/linux).