Skip to content

Commit

Permalink
Update documentation on deploy without docker (#10655)
Browse files Browse the repository at this point in the history 
Fix #10623
  • Loading branch information
@JREastonMarks
JREastonMarks authored Feb 27, 2024
1 parent b417977 commit a7d71b7
Show file tree
Hide file tree
Showing 6 changed files with 58 additions and 146 deletions.
31 changes: 2 additions & 29 deletions docs/deployment/deploy-without-docker/Build-from-Source.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
124 changes: 19 additions & 105 deletions docs/deployment/deploy-without-docker/Deploying.md
View file
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.
7 changes: 4 additions & 3 deletions docs/deployment/deploy-without-docker/Import-the-Seed-Database.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
20 changes: 16 additions & 4 deletions docs/deployment/deploy-without-docker/Load-Sample-Cancer-Study.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 <your_cbioportal_dir>/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
```
Expand All @@ -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 <your_cbioportal_dir>/core/src/main/scripts/importer
cd cbioprtal-core/src/main/scripts/importer
```

and then run the following command:
Expand All @@ -64,7 +76,7 @@ Validation of study succeeded with warnings.
To import the sample study:

```
cd <your_cbioportal_dir>/core/src/main/scripts/importer
cd cbioportal-core/src/main/scripts/importer
```

and then run the following command:
Expand Down
18 changes: 15 additions & 3 deletions docs/deployment/deploy-without-docker/Pre-Build-Steps.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand All @@ -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.
Expand All @@ -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;
Expand Down
4 changes: 2 additions & 2 deletions docs/deployment/deploy-without-docker/Software-Requirements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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```

Expand Down

0 comments on commit a7d71b7

Please sign in to comment.