This project was bootstrapped with Create React App. See notes below about Available npm scripts for local development.
Science Portal is distributed as a war file.
Node.js npm react developer tools in chrome: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi/related?hl=en host file entry (see Environment Files)
A .env file is used by npm to determine what URL, port and protocol to use in launching a local server. As such, it must be resolvable by npm in order to start up a local instance. Simplest is to place it in the root of your application directory. Other methods are possible, documentation can be found here: https://create-react-app.dev/docs/adding-custom-environment-variables/
Contents should be similar to below. Use one entry per line or npm won't recognize the values:
PORT=443
HOST=dev-www.canfar.net
HTTPS=true
This file should NOT be included when the repository is cloned. When setting the HOST name keep in mind there are CORS issues with having a domain different than where skaha is deployed.
(*) If this file is not in place, 'npm start' will start the app up on localhost which won't work. If the .env file is in place in the
(*) If your IDE can't find a .env file that is clearly in the root of your project, make sure the references to node and npm locations are correct for the project.
NOTE: the HOST entry can be whatever you wish, as long as it also appears in your local /etc/hosts file associated with the LOCALHOST ip, ie:
127.0.0.1 dev-www.canfar.net
Depending on where the skaha service sits and any CORS issues that might arise, it's suggested that the domain name match where skaha is served from (ie rc-uv.canfar.net, wher 'canfar.net' matches what's been put in your local host file.)
- Clone the repo
- Open in your ide, install project dependencies using npm (run 'npm install', it reads the package.json file) The node_modules folder will be addedin this step. First index can take some time.
- Set /etc/hosts entry for local URL
- Set up .env file to match /etc/hosts entry
- Use 'npm start' to start up the local instance
NOTE: current test configuration points to rc, so you'll need the vpn up for the registry client reference to work, and you'll need to log in to rc in order for skaha permissions to work.
- edit code in either /public/dev/js or /react directories
- use 'npm start' to test function locally
- use standard deployment to test vm for further testing:
- run './gradlew clean build', then rsync build/libs/science-portal.war to the vm into /usr/local/cadc/webapps/science-portal.war
Make sure to have a .gitignore entry to exclude the war file distribution folder /src/main/webapp/dist. This will prevent the compiled react app and distribution javascript from being checked into github.
You could have these entries in .gitignore as well: .env (if you have something other than the default host URL set)
There's 2 environments to consider:
- a dev environment that allows work on your local machine
- a vm/rc/production environment that allows work in the war file environment
(Could be that containerizing Science Portal would alleviate this difference, but that work hasn't been done yet.)
Science Portal has a React core with an HTML + javascript framework.
There are 2 types of config:
-
one that only changes when the code may need to change (ie support for session types) This is included in sessiontype_map_en.json. The location of this file is slightly different for dev and dist (the latter being controlled by the copy done in build.gradle.) The location of the file is fed into the app using the contentBase variable, found in either /public/test_config/sp_test_config.js or /src/main/webapp/dist_config/sp_dist_config.js
-
one that changes during run time (ie banner text, or registry location.) This is found in org.opencadc.science-portal.properties as deployed on the server (rc, a dev vm or production)
3 differences:
- How config it applied
- How app is built & served
- How authentication works
The advantage of working on your local machine is it's far easier to step through the React App files in web Browser tools, as the files are treated separately, and are visible as they are written rather than how they are generated into the single react-app.js file. In the war file environment, there are browser plugins available to help debug React apps.
-
Granularity of service access can be controlled in dev. This is done using public/test_config/sp_test_config.js using an object that lists service URLS Science Portal will use. Use this in /public/index.html in the call to instantiate the app, using 'URLOverrides'.
-
Main page of the app is /public/index.html. All file includes here point to /public folder locations. npm uses this file to serve the app via websockets to localhost.
-
Until there's the ability to have a local version /access service running, authentication can't be handled correctly running on localhost. The isDev flag (found in /public/index.html where the app is initialized,) will allow the page to move forward without having this service in place.
-
Registry location (and through that service location) is provided in the *.properties file deployed on the tomcat server
-
Main page of the app is /src/main/webapp/index.jsp. Deployed as a war file to tomcat
-
Authentication requires a local copy of /access to be present so that cookie augmentation can happen properly
Work in the /public directory, check as much function as you can locally before deploying to a vm to test authentication.
WARNING: Files in /src/main/webapp/dist are DELETED during the build phase. Make sure any changes you make go into /public/dev/js/* !!!
src/main/react for react files public/dev/js for javascript files public/dev/json for JSON config files
science-portal.war will be built and assembled into a WAR file,
./gradlew clean build
build/libs/science-portal).war
ssh to deployment location as science-portal.war
./gradlew build performs the following steps:
- Build React App
- Copy react-app.js into dist directory
- Copy public/dev content into dist directory (javascript and json config files)
- Assemble WAR
public/js goes to src/main/webapps/dist/js react app goes to src/main/webapps/dist/react-app.js
canfar-root.war files this is still dependent on: <script type="text/javascript" src="/cadcJS/javascript/cadc.registry-client.js"></script> <script type="text/javascript" src='/cadcJS/javascript/org.opencadc.js'></script> <script type="text/javascript" src='/cadcJS/javascript/cadc.uri.js'></script> <script type="text/javascript" src="/cadcJS/javascript/cadc.user.js"></script> <script type="text/javascript" src="/canfar/javascript/cadc.redirect.util.js"></script>
<!-- Adding gdpr cookie banner -->
<script type="text/javascript" src="/cadcJS/javascript/cadc.gdpr.cookie.js"></script>
<link type="text/css" href="/canfar/css/cadc.gdpr.cookie.css" rel="stylesheet" media="screen">
... this documentation came from a react app tutorial.
In the project directory, you can run:
Runs the app in the development mode.
Open http://localhost:3000 to view it in your browser.
The page will reload when you make changes.
You may also see any lint errors in the console.
Launches the test runner in the interactive watch mode.
See the section about running tests for more information.
Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.
The build is minified and the filenames include the hashes.
Your app is ready to be deployed!
See the section about deployment for more information.
Note: this is a one-way operation. Once you eject, you can't go back!
If you aren't satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.
Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.
You don't have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.
You can learn more in the Create React App documentation.
To learn React, check out the React documentation.
This section has moved here: https://facebook.github.io/create-react-app/docs/code-splitting
This section has moved here: https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size
This section has moved here: https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app
This section has moved here: https://facebook.github.io/create-react-app/docs/advanced-configuration
This section has moved here: https://facebook.github.io/create-react-app/docs/deployment
This section has moved here: https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify