diff --git a/docs/deployment/deploy-without-docker/Build-from-Source.md b/docs/deployment/deploy-without-docker/Build-from-Source.md index 82b5529ffde..52625640bd1 100644 --- a/docs/deployment/deploy-without-docker/Build-from-Source.md +++ b/docs/deployment/deploy-without-docker/Build-from-Source.md @@ -2,37 +2,10 @@ ## Building with Maven -While building, you must point the environment variable `PORTAL_HOME` to -the root directory containing the portal source code. - -For example, run a command like the following if on macOS: -``` -export PORTAL_HOME=/Users/ecerami/dev/cbioportal -``` - -To compile the cBioPortal source code, move into the source directory and -run the following maven command: +To compile the cBioPortal source code, move into the root directory and run the following maven command: ``` mvn -DskipTests clean install ``` -After this command completes, you will find a `cbioportal.war` file suitable -for Apache Tomcat deployment in `portal/target/`. It is not neccessary to -install Tomcat yourself, since a command line runnable version of Tomcat is -provided as a dependency in `portal/target/dependency/webapp-runner.jar`. - -However, if you will be deploying to a standalone Tomcat installation, and -if you have configured Tomcat to use the Redisson client for user session -management, you should expect a clash between the Redisson client being -used for session management and the Redisson client which is embedded in -the cbioportal.war file for the optional "redis" persitence layer caching -mode. In this case, you should avoid using the "redis" option for the portal -property `persistence.cache_type` and you should prevent the Redisson -client from being packaged in cbioportal.war by building with this command -instead: - -##### alternative for standalone tomcat deployments which use redis session management -``` -mvn -Dexclude-redisson -DskipTests clean install -``` +Note: cBioPortal 6.X requires Java 21 diff --git a/docs/deployment/deploy-without-docker/Deploying.md b/docs/deployment/deploy-without-docker/Deploying.md index 119e2f6c8f5..ad4363f9c45 100644 --- a/docs/deployment/deploy-without-docker/Deploying.md +++ b/docs/deployment/deploy-without-docker/Deploying.md @@ -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. diff --git a/docs/deployment/deploy-without-docker/Import-the-Seed-Database.md b/docs/deployment/deploy-without-docker/Import-the-Seed-Database.md index 8e2453a34a6..fdab0c8463e 100644 --- a/docs/deployment/deploy-without-docker/Import-the-Seed-Database.md +++ b/docs/deployment/deploy-without-docker/Import-the-Seed-Database.md @@ -39,11 +39,12 @@ After download, the files can be unzipped by entering the following command: 4. (optional : support for microRNA genomic profiles) Import constructed gene table records for microRNA genomic profiles. Currently, cBioPortal supports the combined display of copy number alterations (generally reported for microRNA precursors) and expression (generally reported for microRNA mature forms) by adding gene table records which represent the combination of microRNA precursor and microRNA mature form. Appropriate aliases are added to the gene_alias table so that both the name of the precursor and the name of the mature form are recognized references to the combination. - After the code has been successfully configured and built, you can import the needed microRNA records by running the following command from the $PORTAL_HOME directory: +This involves downloading the cBioPortal Core code located [here](https://github.com/cBioPortal/cbioportal-core). + +After the code has been successfully configured and built, you can import the needed microRNA records by running the following command from the cBioPortal core directory: - ``` java -cp scripts/target/scripts-*.jar org.mskcc.cbio.portal.scripts.ImportGeneData -microrna core/src/main/resources/micrornas.tsv - ``` + **Important:** Please be aware of the version of the seed database. In the [README on datahub](https://github.com/cbioportal/datahub/blob/master/seedDB/README.md), we stated which version of cBioPortal is compatible with the current seed database. diff --git a/docs/deployment/deploy-without-docker/Load-Sample-Cancer-Study.md b/docs/deployment/deploy-without-docker/Load-Sample-Cancer-Study.md index 2435530ebb5..37c653026de 100644 --- a/docs/deployment/deploy-without-docker/Load-Sample-Cancer-Study.md +++ b/docs/deployment/deploy-without-docker/Load-Sample-Cancer-Study.md @@ -4,7 +4,19 @@ Once you have confirmed that the cBioPortal server is installed, you are ready to import data. Importing a sample study is recommended to verify that everything is working correctly. -The cBioPortal distribution includes a [small dummy study, `study_es_0`](https://github.com/cBioPortal/cbioportal/tree/master/core/src/test/scripts/test_data/study_es_0), which contains all datatypes supported by cBioPortal. This document describes how to import the prerequisites for the sample study and how to import the study itself. +cBioPortal Core has a [small dummy study, `study_es_0`](https://https://github.com/cBioPortal/cbioportal-core/tree/main/src/test/scripts/test_data/study_es_0), which contains all datatypes supported by cBioPortal. This document describes how to import the prerequisites for the sample study and how to import the study itself. + + +## Download and Build cBioPortal Core + +``` + git clone https://github.com/cBioPortal/cbioportal-core.git + cd cbioportal-core + git checkout main + mvn -DskipTests clean install +``` + + ## Set the PORTAL_HOME environment variable @@ -26,7 +38,7 @@ export PORTAL_HOME=/Users/johndoe/cbioportal The sample gene panel has to be imported before gene panel study data can be added to the database. ``` -cd /core/src/main/scripts +cd cbioportal-core/src/main/resources/scripts ./importGenePanel.pl --data ../../test/scripts/test_data/study_es_0/data_gene_panel_testpanel1.txt ./importGenePanel.pl --data ../../test/scripts/test_data/study_es_0/data_gene_panel_testpanel2.txt ``` @@ -44,7 +56,7 @@ First it's useful to validate the study `study_es_0`, to check if the data is fo To do so, go to the importer folder: ``` -cd /core/src/main/scripts/importer +cd cbioprtal-core/src/main/scripts/importer ``` and then run the following command: @@ -64,7 +76,7 @@ Validation of study succeeded with warnings. To import the sample study: ``` -cd /core/src/main/scripts/importer +cd cbioportal-core/src/main/scripts/importer ``` and then run the following command: diff --git a/docs/deployment/deploy-without-docker/Pre-Build-Steps.md b/docs/deployment/deploy-without-docker/Pre-Build-Steps.md index b2a48bd78ca..dfb7cf2c7e9 100644 --- a/docs/deployment/deploy-without-docker/Pre-Build-Steps.md +++ b/docs/deployment/deploy-without-docker/Pre-Build-Steps.md @@ -5,6 +5,7 @@ Make sure that you have cloned the last code, and make sure you are on the `master` branch: ``` git clone https://github.com/cBioPortal/cbioportal.git + cd cbioportal git checkout master ``` @@ -23,6 +24,17 @@ log config, which you can then override easily. To modify the logging during tests the same EXAMPLE file can be copied to the relevant test resources folder. +## Prepare the global configuration file + +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: + +``` +cd src/main/resources +cp application.properties.EXAMPLE application.properties +``` + +For more information about the `application.properties` file, see the [reference](/deployment/customization/Customizing-your-instance-of-cBioPortal.md) page. + ## Create the cBioPortal MySQL Databases and User You must create a `cbioportal` database and a `cgds_test` database within MySQL, and a user account with rights to access both databases. This is done via the `mysql` shell. @@ -42,13 +54,13 @@ You must create a `cbioportal` database and a `cgds_test` database within MySQL, mysql> create database cgds_test; Query OK, 1 row affected (0.00 sec) - mysql> CREATE USER 'cbio_user'@'localhost' IDENTIFIED BY 'somepassword'; + mysql> CREATE USER 'cbio'@'localhost' IDENTIFIED BY 'P@ssword1'; Query OK, 0 rows affected (0.00 sec) - mysql> GRANT ALL ON cbioportal.* TO 'cbio_user'@'localhost'; + mysql> GRANT ALL ON cbioportal.* TO 'cbio'@'localhost'; Query OK, 0 rows affected (0.00 sec) - mysql> GRANT ALL ON cgds_test.* TO 'cbio_user'@'localhost'; + mysql> GRANT ALL ON cgds_test.* TO 'cbio'@'localhost'; Query OK, 0 rows affected (0.00 sec) mysql> flush privileges; diff --git a/docs/deployment/deploy-without-docker/Software-Requirements.md b/docs/deployment/deploy-without-docker/Software-Requirements.md index d6b2fed8815..813caad7366 100644 --- a/docs/deployment/deploy-without-docker/Software-Requirements.md +++ b/docs/deployment/deploy-without-docker/Software-Requirements.md @@ -16,13 +16,13 @@ The session service uses MongoDB 3.6.6 ## Java -As of this writing, the cBioPortal can be compiled and run from Java 11 and above. The software can be found and download from the [Oracle](https://www.oracle.com/us/technologies/java/overview/index.html) website. +cBioPortal requires Java 12 and above. The software can be found and download from the [Oracle](https://www.oracle.com/us/technologies/java/overview/index.html) website. On Ubuntu: ```sudo apt-get install default-jdk``` ## Apache Maven -The cBioPortal source code is an [Apache Maven](https://maven.apache.org/) driven project. The software needs to be downloaded and installed prior to building the application from source code. It can be found on the [Apache Maven](https://maven.apache.org/download.cgi) website. We are currently using version 3.5.4. +The cBioPortal source code is an [Apache Maven](https://maven.apache.org/) driven project. The software needs to be downloaded and installed prior to building the application from source code. It can be found on the [Apache Maven](https://maven.apache.org/download.cgi) website. We are currently using version 3.9.5. On Ubuntu: ```sudo apt-get install maven```