Versions Compared

Version Old Version 111 New Version Current
Changes made by

Anthony Williams

Nick Grosenbacher

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Clarify URL of app in development, add commented dev stack property to settings.xml example

...

  • Java (Corretto JDK 11+ recommended)

  • Maven 3

  • DockerYarn

  • v1pnpm v9

Set up your GitHub fork and a local repository

  1. Create a GitHub user account if you don't already have one.

  2. Set up your local git environment according to Sage’s GitHub Security guidance /wiki/spaces/IT/pages/802881544

  3. Fork the Sage-Bionetworks SynapseWebClient repository into your own GitHub account: https://help.github.com/articles/fork-a-repo

  4. Clone your fork of SynapseWebClient project to your local machine and enter the project root directory

    Code Block
    languagebash
    git clone https://github.com/[YOUR GITHUB NAME]/SynapseWebClient.git
cd SynapseWebClient

  5. 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!):

    Code Block
    git secrets --install
git secrets --register-aws

  6. Set up upstream with

    Code Block
    git remote add upstream https://github.com/Sage-Bionetworks/SynapseWebClient

  7. Fetch and merge changes from the Sage Bionetworks repo, which was named upstream: 

    Code Block
    git fetch upstream

  8. Configure or update your Maven configuration settings.xml

    1. The file needs to placed in $HOME/.m2/settings.xml (e.g. jane/.m2/settings.xml)

    2. This should be the content of this file:

      settings.xml

      Code Block
      languagexml
      <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <usePluginRegistry/>
  <offline/>
  <pluginGroups/>
  <servers/>
  <mirrors/>
  <proxies/>
  <profiles>
    <profile>
      <id>dev-environment</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
		<org.sagebionetworks.portal.endpoint>http://127.0.0.1:8888/Portal.html</org.sagebionetworks.portal.endpoint>
        <org.sagebionetworks.repositoryservice.endpoint>https://repo-prod.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint>
        <!-- insert properties described below here -->
        <!-- <org.sagebionetworks.repositoryservice.endpoint>https://repo-staging.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint> -->
        <!-- Uncomment the property below to limit GWT permutations and speed up build timeIf you want to point to a different stack (staging, dev), comment out the above and uncomment one of the below -->
        <!-- <gwt<org.sagebionetworks.modulerepositoryservice.suffix>Debug</gwt.module.suffix> -->endpoint>https://repo-staging.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint> -->
        </properties>
!-- <org.sagebionetworks.repositoryservice.endpoint>https://repo-dev.dev.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint> -->
   </profile>   </profiles>   <activeProfiles/>
</settings>

  9. Verify you can build the project and run the unit tests:

    Code Block
    mvn clean install

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.

Code Block
 pnpm nx run SageAccountWeb:start --port=3000 --host

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

...

titleAlternative ways to run SynapseWebClient in development mode

...

    1. <!-- Uncomment the property below to limit GWT permutations and speed up build time -->
        <!-- <gwt.module.suffix>Debug</gwt.module.suffix> -->
      </properties>
    </profile>
  </profiles>
  <activeProfiles/>
</settings>

  2. Verify you can build the project and run the unit tests:

    Code Block
    mvn clean install

Development

You may use an IDE of your choice. Instructions for setting up IntelliJ IDEA and Eclipse can be found below.

Running SynapseWebClient in development mode requires many different services, including the GWT Codeserver, a Vite codeserver, a Java servlet (Tomcat), and the Sage Bionetworks Account site (required to sign in via UI). For convenience, we maintain a few different ways to run SWC in development mode.

Expand
titleRunning all services in Docker containers (docker compose) [PREFERRED]

To run the app in development mode in a set of Docker containers, you can run pnpm start:<stack>, where stack is one of development,staging,production. This will invoke docker compose to instantiate a container for each service required to run the app in development mode. The latest version of the accounts site (SageAccountWeb) will also be launched on port 3000 as a convenience.

Expand
titleDevelopment mode using native Java/Maven installation

To run the app in development mode, run pnpm install then pnpm dev. This will launch three processes:

  • The GWT Codeserver, which compiles Java to JavaScript, and watches for source changes

  • The Vite codeserver, which bundles JavaScript assets and 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

Note that this does NOT run the Sage account management application (SageAccountWeb), which is separate from SWC. If you want to log in through the UI, you must run SageAccountWeb on port 3000. You can either run SageAccountWeb in synapse-web-monorepo, or you can run the latest Docker image for SageAccountWeb.

Running the local version of SageAccountWeb

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.

Code Block
 pnpm nx run SageAccountWeb:start --port=3000 --host --mode=development

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 (i.e. --mode=production or --mode=staging).

Running the accounts site in a Docker image

You can run the latest version of the accounts site (synapse-web-monorepo/main) with the following command:

Code Block
docker run -it --rm -d -p 3000:80 --name SageAccountWeb ghcr.io/sage-bionetworks/sage-account-web:latest-development

If you want the site to point to staging/production, change development in the image tag to the stack you want to point to.

Alternative ways to run SynapseWebClient in development mode

Instead of running pnpm dev, you can alternatively directly use the GWT Maven plugin (e.g. mvn gwt:run) or an IDE integration. Please note that depending on your IDE/plugin configuration, your environment may be subtly different than the production system (e.g. many GWT plugins deploy a Jetty server, when we use Tomcat in production), which can result in subtle differences in behavior.

Once the service is started, you should be able to see the app at http://127.0.0.1:8888/ .

As you make changes to the source code and static assets, changes will be picked up in the app when you refresh the page.

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.

...

link the synapse-react-client

...

project.

  1. In the SynapseWebClient directory, run

    Code Block
    yarnpnpm link ../path/to/synapse-web-monrepo/packages/synapse-react-client

    This will create a symlink on your machine so the node_modules/synapse-react-client directory points to your local synapse-react-client directory.

  2. Make desired changes in the synapse-react-client project

  3. Rebuild the JavaScript artifacts for synapse-react-client (in synapse-web-monorepo, run pnpm nx run synapse-react-client:build)

  4. If you’re running yarn pnpm 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)Disable Cache, and leave the browser devtools open)

Info

If you’re using Docker Compose to run the development server, you must add your locally-linked package as a volume on the container. Instructions on how to do this are in compose-link.yml.

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:

...

pnpm unlink synapse-react-client

...

.

Note

Linking a package updates the lockfile to reference the local repository, so you must unlink the package before you commit changes to the lockfile.

IDE Setup Instructions

This section contains instructions for setting up various IDEs to develop SynapseWebClient.

...

Expand
titleSetup with Intellij IDEA

  1. Download IntelliJ IDEA 

    1. The community edition is free

    2. The Ultimate edition requires purchasing a license. It includes enhanced support for GWT, but it’s not necessary for development. 

  2. Import the SynapseWebClient project into IntelliJ by File → New Project From Existing Sources... <Select Path to SWC Location>

  3. Set up IntelliJ to directly call yarn pnpm dev

    1. Run → Edit Configurations…

    2. Click “Add New Configuration” → npm

    3. Set the following options

      • Command: run

      • Script: dev

      • Package manager: yarnpnpm

Technologies used

There are several technologies that we are currently utilizing in the portal. The following is a list of primers for each:

...