bootstrap

TODO: The Build and Execution steps of README.md are still relevant. We should incorporate that information into this doc and then replace README.md with a link to this doc.

NOTE: Before cloning the contents of this repository, please see https://sagebionetworks.jira.com/wiki/spaces/IT/pages/802881544/Using+GitHub

For an overview of Bridge, see https://developer.sagebridge.org/articles/overview.html

Install/Setup Software

git - Mac: There's already a git executable in /usr/bin. You'll need to run git once to initialize git and all the developer tools you'll need. Linux: ???

Corretto 8 - This is an Open Java implementation, since Oracle no longer provides an official Java 8 implementation. Bridge doesn't currently work in Java 11+. (We haven't tested this in Java 9 or 10.)

You may need to set your $JAVA_HOME to point to your Corretto installation. You can verify the correct version of Java by running java -version or mvn -version (see below).

If you're still having problems, uninstall your Java browser plugin. The Java browser plugin is known to interfere with the JDK.

IDE of your choice - I like IntelliJ. Another popular choice is Eclipse.

Maven - This is the build system we use. Simplest way to install it is to install MacPorts, and then run "sudo port install maven3" to install.

Redis - Used by Bridge Server as a cache. Mac: "sudo port install redis". Type "redis-server" to start. This will start running in your current terminal window. You will need to switch to a new terminal window (or tab) to continue work.

MySQL Server - For local testing of SQL stuff. The alternative is to spin up an Amazon RDS instance. (IMPORTANT: Bridge currently uses 5.7. There are significant differences between 5.7 and 8.0. Make sure you download and install 5.7. You may need to click through to Archives in the download page to find a compatible version of MySQL. Note: At this time, it looks like the latest version available on Mac is 5.7.31.) (Note: Newer versions of OS X may fail to open the MySQL installer because Apple cannot verify the developer. As long as you downloaded the file from the MySQL website, this app should be safe to install. To override OS X, see the instructions here.)

• Note the username and password on install.

• To launch on OS X, go to System Preferences, MySQL, click Start MySQL Server. (Optionally, check/uncheck Automatically Start MySQL Server on Startup.)

• MySQL CLI comes with MySQL Server. To use, add /usr/local/mysql/bin to path. To connect, run "mysql -u (username) -p".

• On your first connect, you'll need to reset your password with

  SET PASSWORD FOR '(username)'@'localhost' = PASSWORD('(new password)');
  

  or if it doesn't work, use

  ALTER USER '(username)'@'localhost' IDENTIFIED BY '(new password)';
  

• Optionally install MySQL Workbench, a GUI for MySQL.

Creating a Fork

Create a fork of the BridgeServer2 project (using the Fork button in the upper right of the GitHub page). Clone your fork of the BridgeServer2 project, either using "git clone" or by going through your IDE.

You'll want to create a remote of the main fork, so that you can easily update with changes from main. To do so, use the following git command fromt the root of your local BridgeServer2 project: git remote add sage https://github.com/Sage-Bionetworks/BridgeServer2.git

To update from main, use: git pull sage develop

Initial Setup

In your MySQL Workbench or an equivalent tool, run the command CREATE DATABASE BridgeDB.

Before Bridge will run, you will need a local ~/BridgeServer2.conf file with the passwords to the services the application uses (AWS, Stormpath, etc.). This is not in version control. If you work for Sage, contact a team member to get the contents of this file. If you are developing externally, you will need to create accounts and API keys with these external services in order for Bridge to work. See the src/main/resources/BridgeServer2.conf file for all the properties that are going to need to be created and set.

You'll need to add the following 3 config lines:

hibernate.connection.password = your password here
hibernate.connection.url = jdbc:mysql://localhost:3306/your-db-name-here
hibernate.connection.username = your username here

You will need to add the following bootstrap account to your ~/BridgeServer2.conf file.

admin.email = your.email@sagebase.org
admin.password = any password
admin.synapse.user.id = you synapse user ##

Where "your.email" is your Sage email address (or your email address from your org if you're outside of Sage). Using the Synapse user ID (which is a number), you will also associate this account with a Synapse account that you control. (If you work at Sage, ask your co-workers for the credentials for the shared test Synapse account.) This is so the admin account can switch between Bridge apps during the integration tests (an email/password account is not sufficient for this).

Setting up Synapse OAuth

Finally, you can define a password so you can access the system to set up OAuth initially, as this bootstrap admin account will not work for the integration tests until Bridge has information about the Synapse OAuth client (see instructions in the next step). The password can be anything since this is for your local test server only. However by default, passwords must meet the following criteria:

• minimum 8 characters
• at least one lowercase, uppercase, number, and symbol

The account will be created when the system is first bootstrapped so you can access it. Because it is an admin account in the bootstrap API study, it can be used to create other apps and to switch into those apps using specific administrative APIs in order to create bootstrap users in those apps. You may choose to delete this account in a production environment once you have finished configuring administrative accounts.

Finally, if you intend to run the Bridge Study Manager locally on 127.0.0.1, and you wish to sign in using your Synapse account, you will need to add the OAuth client credentials for the client that has been registered with Synapse:

synapse.oauth.client.id = your-value-here
synapse.oauth.client.secret = your-value-here

Synapse OAuth clients have already been registered for the three environments in which the Bridge Study Manager runs (127.0.0.1, note that 'localhost' cannot be registered with Synapse; research-staging.sagebridge.org; and staging.sagebridge.org). The client ID and secret for each of these environments are in the Bridge Shared folder of LastPass (see the "Synapse OAuth Client for Bridge Study Manager" entries). NOTE that you must still create a Bridge account in each study, and associate it to your Synapse user ID, in order to be able to sign in via Synapse to work with that study. So before you delete the bootstrap user, you will want to sign in to the bootstrap API study and create a cross-study admin account that is associated to your Synapse account.

If you want to run the BridgeIntegrationTests repo against the server, you must also put the same properties with the same credentials in your ~/bridge-sdk.properties file. That configuration file will be read by the integration tests to use your bootstrap account and create all the necessary users for the tests.

Running Bridge

Before running Bridge Server, make sure redis is running (see section above). Then, run "mvn spring-boot:run". This will take about a minute to launch the server and to bootstrap DynamoDB tables and MySQL tables.

You will know it's running when you see a message that says "Logging heartbeat..." Another way to test if Bridge Server is running is by going to http://localhost:9000/v1/apps?summary=true This is one of the few URLs that doesn't require login or POST parameters, and it outputs some JSON that your browser can render, so you can see that Bridge is up and running and serving requests correctly.

NOTE: If this step fails, you may not be able to run it again until you've resolved your problem, and deleted any records created in your Dynamo Study, StudyConsent1 and Subpopulation tables. The DDB bootstrapper will by default create your DynamoDB tables (and all other AWS resources) in us-east-1 (N Virginia). You may also need to clear your Redis cache (redis-cli flushall), depending on how far you proceeded before encountering an error. You may also need to drop all your MySQL database tables.

Testing Bridge

The simplest way to test Bridge is to run the Integration Tests.

Alternatively, you can send raw HTTP requests to localhost on port 9000. You can use curl, wget, or a tool like Postman.

Example HTTP Requests

The following request will sign in to Bridge.

POST http://localhost:9000/v3/auth/signIn

{
  "appId":"api",
  "email":"your.email@sagebase.org",
  "password":"any password"
}

Use the same password that you specified in your ~/BridgeServer2.conf.

If this request successfully authenticates, it will return a JSON blob with a "sessionToken" field. Pass this token into subsequent HTTP requests using the Bridge-Session header.

Debugging

Run mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"

This will start the Bridge server with remote debugging on port 5005 (the default debugging port in most IDEs). For examples of requests to send, see our API docs. (Note: Bridge still takes normal HTTP requests on port 9000.)

Troubleshooting

My unit tests take a very long time. There is a known issue in Java 8 where sometimes InetAddress.getLocalhost() takes a long time (5 seconds to a minute). The Maven Surefire test report generator calls this function in a loop. As a result, sometimes unit tests appear to take a very long time or appear to hang.

To solve this, run hostname in your command prompt to get your hostname. Then edit your /etc/hosts. There should be two lines that look like

127.0.0.1  localhost
::1        localhost

Append your hostname to the end of each of those lines. For example, if your hostname is Dwaynes-MacBook-Pro.local, then the updated lines should look like

127.0.0.1  localhost Dwaynes-MacBook-Pro.local
::1        localhost Dwaynes-MacBook-Pro.local

Source