Developer Bootstrap
UI Development
Prerequisite software to install
Java (Corretto JDK 11+ recommended)
Maven 3
Docker
Yarn v1
Set up your GitHub fork and a local repository
Create a GitHub user account if you don't already have one.
Set up your local git environment according to Sage’s GitHub Security guidance
Fork the Sage-Bionetworks SynapseWebClient repository into your own GitHub account: https://help.github.com/articles/fork-a-repo
Clone your fork of SynapseWebClient project to your local machine and enter the project root directory
git clone https://github.com/[YOUR GITHUB NAME]/SynapseWebClient.git cd SynapseWebClient
If you didn't set up the global pre-commit hook in step #2, set up a local pre-commit hook to detect secrets (do this for all repos that you clone in the future!):
git secrets --install git secrets --register-aws
Set up upstream with
git remote add upstream https://github.com/Sage-Bionetworks/SynapseWebClient
Fetch and merge changes from the Sage Bionetworks repo, which was named upstream:
Configure or update your Maven configuration
settings.xml
The file needs to placed in
$HOME/.m2/settings.xml
(e.g.jane/.m2/settings.xml
)This should be the content of this file:
settings.xml
Verify you can build the project and run the unit tests:
Development
You may use an IDE of your choice. Instructions for setting up IntelliJ IDEA and Eclipse can be found below.
To run the app in development mode, run yarn install
then yarn dev
. This will launch three processes:
The GWT Codeserver, which watches for source changes
A file watcher that monitors changes to static assets, and copies them to the deployed web application directory when they change
An Apache Tomcat Docker container that will host the web application
As you make changes to the source code and static assets, changes will be picked up in the app when you refresh the page.
Running the accounts site to enable sign-in
SynapseWebClient delegates authentication and account management to a separate web application. In order to sign in to a local instance of SynapseWebClient, you must also start a local instance of the account management application. Set up the synapse-web-monorepo project and run the following command.
If your portal instance is configured to use to a different backend stack, you will need to configure SageAccountWeb to also use the same stack.
We have an open ticket to improve this process: SWC-7230
JavaScript dependency development
If you have made changes to a JavaScript dependency (e.g. synapse-react-client), you can see those changes in your local development environment by “linking” the projects. As an example, we will link the synapse-react-client
project.
In the synapse-react-client directory, run
In the SynapseWebClient directory, run
This will create a symlink on your machine so the node_modules/synapse-react-client directory points to your local synapse-react-client directory.
Make desired changes in the synapse-react-client project
Rebuild the JavaScript artifacts for synapse-react-client (
pnpm nx run synapse-react-client:build
)If you’re running
yarn dev
, the changed JavaScript file should automatically be picked up. Refresh your browser window to see the changes (you will likely need to open your browser dev tools → Network → Disable Cache, and leave the browser devtools open)
When you want to unlink synapse-react-client, in the SynapseWebClient directory you can run yarn unlink synapse-react-client
and then yarn install --force
.
Known issues:
Running
yarn install
in SynapseWebClient after linkingsynapse-react-client
breaks thepnpm
installation in the synapse-web-monorepo project. To fix this, runpnpm install --force
in the synapse-web-monorepo project.
IDE Setup Instructions
This section contains instructions for setting up various IDEs to develop SynapseWebClient.
Technologies used
There are several technologies that we are currently utilizing in the portal. The following is a list of primers for each:
React and the Synapse React Client
Further reading: How to create and render a React component in SynapseWebClient
For dependency injection, an example of Inversion of Control (IoC), we are using a combination of GIN and Guice.
Guice - is the base IoC technology but it is only fully functional in Server-side.
Gin - provides basic IoC for GWT client-side code.
Guice Servlet - This is a sub-project of Guice that allows dependency inject into servlets.
HTTP REST calls are currently made using Spring's RestTemplate. http://blog.springsource.com/2009/03/27/rest-in-spring-3-resttemplate/
Mockito testing framework - mock dependent classes/interfaces to isolate test. Verify expected interactions (including async calls).
Bootstrap 3 UI framework (including a number of extras widgets), wrapped for GWT (deprecated).
Markdown-it - for markdown processing . Extended the library by adding a number of plugins, available on npm. The Node.js plugin that's used to orchestrate the processing is called markdown-it-synapse. The source code for many of these plugins is in the synapse-web-monorepo project.
AWS js sdk - direct browser upload/download from s3-like storage.
jquery, moment js, font-awesome, mathjax, plot.ly, twitter, nodeca/pica (browser image resize), SparkMD5 (browser side md5 calculation), nchart and jsplumb (Dave's charting libraries for provenance), Google (analytics, search, closure-library, single sign on).
frontend-maven-plugin to install Node and Yarn at build-time, which provides numerous JavaScript dependencies via NPM.
End-to-end testing
Instructions on running end-to-end tests are included in this README.
How to point to a local instance of the Synapse backend
Follow the instructions on the Platform Bootstrap to set up a local backend stack.
Build and launch a local backend stack. From an up-to-date clone of Synapse-Repository-Services on your local box:
Build the local stack by running
mvn clean install -Dorg.sagebionetworks.database.drop.schema=true
.Now launch it:
Verify the services are running correctly by visiting
http://localhost:8080/services-repository-develop-SNAPSHOT/repo/v1/version
. You should see something like this:
In the SWC project root pom.xml, change the synapse.version tag to
develop-SNAPSHOT
, so that Maven utilizes artifacts that were built by running on your local stack.Update the repository endpoint property in your maven settings.xml file:
Restart the Portal app to load these properties from settings.xml.
Emails will not be sent when pointing to a local repo, the SynapseEmailService will instead write files to the devdata.sagebase.org s3 bucket in format <to_email_address>.json
How to point to a remote stack
Set the repository endpoint parameters in your maven settings.xml file.
To point to the development stack set:
To point to staging set:
To point to production set:
Restart the Portal app to load this property from settings.xml.
Documenting complicated UI in the code
To get the big picture of widget relationships, sometimes it is helpful to have a picture. We are testing the use of tools like https://mermaid.js.org/ to help in these situations.
Compile Report
To generate a compile report, set enableClosureCompiler to false in the root pom.xml