# Deploying the Web Application

# 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 $HOME/cbioportal/application.properties

For more information about the application.properties file, see the reference 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:

export PORTAL_HOME=$HOME/cbioportal

if your properties file is at PORTAL_HOME/application.properties

# Run cBioPortal Session Service

The cBioPortal app requires 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:

# 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

# Run the cbioportal backend

To run the app we use webapp-runner. It's a command line version of Tomcat provided by Heroku. All parameters can be seen with:

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 to enable this.

java \
    -jar \
    -Dauthenticate=noauthsessionservice \
    portal/target/dependency/webapp-runner.jar \

# Optional login

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 section to read more about these features.

java \
    -jar \
    -Dauthenticate=social_auth_google,social_auth_microsoft \
    portal/target/dependency/webapp-runner.jar \

Google and Microsoft live are supported as optional login currently. Possible values for authenticate are


One needs to set the Google/Microsoft related configurations in the application.properties file:

#For Google

#For Microsoft

See Google's Sign in Documentation to obtain these values.

See Microsoft Sign in Documentation to obtain these values.

# Required login

java \
    -jar \
    portal/target/dependency/webapp-runner.jar \

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 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).

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

# Important

  • 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 for more information).