-
Notifications
You must be signed in to change notification settings - Fork 511
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into mutation-data-counts
- Loading branch information
Showing
25 changed files
with
247 additions
and
405 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,131 +1,45 @@ | ||
| # Deploying the Web Application | ||
|
|
||
| ## Prepare the global configuration file | ||
| ## Before running cbioportal backend | ||
|
|
||
| The portal is configured using a global configuration file, `application.properties`. An example file is available in the `src/main/resources` folder. Use it as a template to create your own: | ||
| You will need to update the src/main/resources/applications.properties to include your DB connection information. | ||
|
|
||
| ``` | ||
| cd src/main/resources | ||
| cp application.properties.EXAMPLE $HOME/cbioportal/application.properties | ||
| ``` | ||
|
|
||
| For more information about the `application.properties` file, see the [reference](/deployment/customization/Customizing-your-instance-of-cBioPortal.md) page. | ||
|
|
||
| Several scripts of cBioPortal use this `application.properties` file to get info like db connection parameters. You can indicate the folder where this file is with an environment variable: | ||
| The configuration defined in `application.properties` can also be passed as command line arguments. The priority of property loading is as follows: | ||
|
|
||
| ``` | ||
| export PORTAL_HOME=$HOME/cbioportal | ||
| ``` | ||
| 1. `-D` command line parameters overrides all | ||
| 2. `src/main/resources/application.properties` | ||
| 3. `application.properties` supplied at compile time | ||
| 4. Defaults defined in code | ||
|
|
||
| if your properties file is at `PORTAL_HOME/application.properties` | ||
| Note that the `authenticate` property is currently required to be set as a command line argument, it won't work when set in `application.properties` (See issue [#6109](https://github.com/cBioPortal/cbioportal/issues/6109)). | ||
|
|
||
| ## Run cBioPortal Session Service | ||
| Some scripts require a `${PORTAL_HOME}/application.properties` file, so it is best to define the properties there. | ||
|
|
||
| The cBioPortal app requires [session service](/Architecture-Overview.md#session-service). For instructions on how to run this without Docker see https://github.com/cBioPortal/session-service#run-without-docker. Once this is working, update the properties file: | ||
| For more information about the `application.properties` file, see the [reference](/deployment/customization/Customizing-your-instance-of-cBioPortal.md) page. | ||
|
|
||
| ```bash | ||
| # session-service url: http://[host]:[port]/[session_service_app]/api/sessions/[portal_instance]/ | ||
| # example session-service url: http://localhost:8080/session_service/api/sessions/public_portal/ | ||
| # see: https://github.com/cBioPortal/session-service | ||
| session.service.url= | ||
| ``` | ||
|
|
||
| ## Run the cbioportal backend | ||
|
|
||
| To run the app we use `webapp-runner`. It's a command line version of Tomcat provided by [Heroku](https://github.com/jsimone/webapp-runner). All parameters can be seen with: | ||
| To run the backend execute the following commabd | ||
|
|
||
| ``` | ||
| java -jar portal/target/dependency/webapp-runner.jar --help | ||
| ``` | ||
|
|
||
| This runs the app in the foreground. If a port is already in use it will raise an error mentioning that. To change the port use the `--port` flag. | ||
|
|
||
| There are three main ways to run the portal: without authentication, with optional login and with required login. All of them require the cBioPortal session service to be running. | ||
|
|
||
| ### Without authentication | ||
|
|
||
| In this mode users are able to use the portal, but they won't be able to save their own virtual studies and groups. See the [optional login section](#optional-login) to enable this. | ||
|
|
||
| ```bash | ||
| java \ | ||
| -jar \ | ||
| -Dauthenticate=noauthsessionservice \ | ||
| portal/target/dependency/webapp-runner.jar \ | ||
| portal/target/cbioportal.war | ||
| java -jar target/cbioportal-exec.jar | ||
| ``` | ||
|
|
||
| ### Optional login | ||
| This runs the app in the foreground. If a port is already in use it will raise an error mentioning that. To change the port use the `--server.port` flag. | ||
|
|
||
| In this mode users can see all the data in the portal, but to save their own groups and virtual studies they are required to log in. This will allow them to store user data in the session service. See the [tutorials](https://www.cbioportal.org/tutorials) section to read more about these features. | ||
|
|
||
| ```bash | ||
| java \ | ||
| -jar \ | ||
| -Dauthenticate=social_auth_google,social_auth_microsoft \ | ||
| portal/target/dependency/webapp-runner.jar \ | ||
| portal/target/cbioportal.war | ||
| ``` | ||
|
|
||
| Google and Microsoft live are supported as optional login currently. Possible values for authenticate are | ||
| There are three main ways to run the portal: without authentication, with optional login, and with required login. All of them require the cBioPortal session service to be running. | ||
|
|
||
| ```bash | ||
| -Dauthenticate=social_auth_google,social_auth_microsoft | ||
| -Dauthenticate=social_auth_google | ||
| -Dauthenticate=social_auth_microsoft | ||
| ``` | ||
|
|
||
| One needs to set the Google/Microsoft related configurations in the `application.properties` file: | ||
| ### Without authentication | ||
|
|
||
| ``` | ||
| #For Google | ||
| googleplus.consumer.key= | ||
| googleplus.consumer.secret= | ||
| In this mode users are able to use the portal, but they won't be able to save their own virtual studies and groups. | ||
|
|
||
| #For Microsoft | ||
| microsoftlive.consumer.key= | ||
| microsoftlive.consumer.secret= | ||
| ``` | ||
|
|
||
| See [Google's Sign in Documentation](https://developers.google.com/identity/sign-in/web/sign-in#before\_you\_begin) to obtain these values. | ||
|
|
||
| See [Microsoft Sign in Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-web-app-sign-user-app-registration) to obtain these values. | ||
|
|
||
| ### Required login | ||
|
|
||
| ```bash | ||
| java \ | ||
| -Dauthenticate=CHOOSE_DESIRED_AUTHENTICATION_METHOD \ | ||
| -jar \ | ||
| portal/target/dependency/webapp-runner.jar \ | ||
| portal/target/cbioportal.war | ||
| java -jar target/cbioportal-exec.jar -Dauthenticate=false | ||
| ``` | ||
|
|
||
| Change `CHOOSE_DESIRED_AUTHENTICATION_METHOD` to one of `googleplus`, `saml`, `openid`, `ad`, `ldap`. The various methods of authentication are described in the [Authorization and Authentication](/deployment/authorization-and-authentication) section. | ||
|
|
||
| ### Property configuration | ||
|
|
||
| The configuration defined in `application.properties` can also be passed as command line arguments. The priority of property loading is as follows: | ||
|
|
||
| 1. `-D` command line parameters overrides all | ||
| 2. `${PORTAL_HOME}/application.properties` | ||
| 3. `application.properties` supplied at compile time | ||
| 4. Defaults defined in code | ||
|
|
||
| Note that the `authenticate` property is currently required to be set as a command line argument, it won't work when set in `application.properties` (See issue [#6109](https://github.com/cBioPortal/cbioportal/issues/6109)). | ||
|
|
||
| Some scripts require a `${PORTAL_HOME}/application.properties` file, so it is best to define the properties there. | ||
|
|
||
| ### Note for Tomcat Deployers | ||
|
|
||
| Before we were using `webapp-runner`, our documentation recommended a system level installed Tomcat. In this case people might have been using `dbconnector=jndi` instead of the new default `dbconnector=dbcp`. There is a known issue where setting dbconnector in the properties file does not work ([#6148](https://github.com/cBioPortal/cbioportal/issues/6148)). It needs to be set as a command line argument. For Tomcat this means `CATALINA_OPT="-Ddbconnector=jndi"`. | ||
|
|
||
| ## Verify the Web Application | ||
|
|
||
| Lastly, open a browser and go to:\ | ||
| [http://localhost:8080](http://localhost:8080) | ||
|
|
||
| ## Important | ||
| ### With authentication | ||
|
|
||
| * Each time you modify any java code, you must recompile and redeploy the app. | ||
| * Each time you modify any properties (see customization options), you must restart the app | ||
| * Each time you add new data, you must restart the app or call the `/api/cache` endpoint with a `DELETE` http-request (see [here](/deployment/customization/application.properties-Reference.md#evict-caches-with-the-apicache-endpoint) for more information). | ||
| To configure the authentication and authorization please consult the [Authorization](./../authorization-and-authentication/User-Authorization.md) and [Authentication](./../authorization-and-authentication/Authenticating-and-Authorizing-Users-via-keycloak.md) Sections. |
Oops, something went wrong.