CloudBees Web Configuration File

Important note

The cloudbees-web.xml is considered "legacy" - it is not deprecated (yet) - and we don't currently have a plan to get rid of it - but it is the less preferred way to manage environment settings. For this We recommend you look at the Configuration Parameter docs.

When using Servlet containers, the cloudbees-web.xml file provides extra configuration for your application to setup your application ID, datasources binding and extra configuration parameters. Like the standard Servlet Application web.xml, this file should be located in your application's WEB-INF directory.

Basic Structure

Application Environments

It's very common for applications to need customized configuration depending on the environment/mode that application is running in.  The cloudbees configuration file supports an environmment element that you can wrap around your configuration XML so that it is only included if the app is run or deployed with the specified environment name.

This is very commonly used for when running local vs deployed, or in development vs production. Here's an example of how to run with one set of configuration when running locally versus when running deployed to RUN@cloud.

1. Create a configuration with multiple environments
<?xml version="1.0"?>
<cloudbees-web-app xmlns="http://www.cloudbees.com/xml/webapp/1">
 <environment name="prod">
   <appid>ACCOUNT/myapp</appid>
   <context-param>
     <param-name>mypassword</param-name>
     <param-value>PROD_PASSWORD</param-value>
   </context-param>
   <resource name="jdbc/DATASOURCE_NAME" auth="Container" type="javax.sql.DataSource">
     <param name="username" value="DB_USER" />
     <param name="password" value="DB_PASS" />
     <param name="url" value="jdbc:mysql://DB_HOST:3306/DB_NAME" />
   </resource>
 </environment>

 <environment name="dev">
   <appid>ACCOUNT/myapp-dev</appid>
   <context-param>
     <param-name>mypassword</param-name>
     <param-value>DEV_PASSWORD</param-value>
   </context-param>
   <resource name="jdbc/DATASOURCE_NAME" auth="Container" type="javax.sql.DataSource">
     <param name="username" value="DB_USER-dev" />
     <param name="password" value="DB_PASS" />
     <param name="url" value="jdbc:mysql://DB_HOST:3306/DB_NAME-dev" />
   </resource>
 </environment>

 <environment name="local">
   <context-param>
     <param-name>mypassword</param-name>
     <param-value>LOCAL_PASSWORD</param-value>
   </context-param>
   <resource name="jdbc/DATASOURCE_NAME" auth="Container" type="javax.sql.DataSource">
     <param name="username" value="DB_USER-test" />
     <param name="password" value="DB_PASS" />
     <param name="url" value="jdbc:mysql://DB_HOST:3306/DB_NAME-test" />
   </resource>
 </environment>

 <!-- A common database -->
 <resource name="jdbc/DATASOURCE_NAME2" auth="Container" type="javax.sql.DataSource">
   <param name="username" value="DB2_USER" />
   <param name="password" value="DB2_PASS" />
   <param name="url" value="jdbc:mysql://DB_HOST:3306/DB_NAME2" />
 </resource>
</cloudbees-web-app>

2. Run the code locally with the "local" environment configuration applied (via the -e flag)
bees run -e local

3. Deploy the "dev" version of the application (deploys as http://myapp-dev.ACCOUNT.staxapps.net)
bees deploy -e dev

4. Deploy the "prod" version of the application (deploys as http://myapp.ACCOUNT.staxapps.net)
bees deploy -e prod

Merging environments

It is also possible to chain together environments so that your app can inherit a set of settings from one environment, and override some of them with another.  For instance, the following command would run the app with the prod environment settings, and then override with settings defined in the local environment:
bees run -e prod,local

System Properties

Use the sysprop element to set system properties during initialization of the app container.
 <sysprop name="PROP_NAME" value="PROP_VALUE" />

JNDI Environment Entries

Use the resource element to define jndi env-entry values:

By default, JNDI env-entries default be being added as Strings.
<resource name="resource_name" value="some string value" type="jndi-env" />

If you need to define a more explicit type that the value is registered as, you can postfix the resource type with the class type.
<resource name="resource_name" value="10" type="jndi-env:java.lang.Integer" />

Usage of cloudbees-web.xml and example

Using cloudbees-web.xml is certainly not necessary if you just want to define system properties and your application just get those values via System.getProperty or as env var for non jvm stacks.

Sometimes it might be useful to use cloudbees-web.xml if you want to define other type of parameters like context parameters or resource parameters or jndi resources.  Some developers also like to define which parameters are required by the app by defining them in the cloudbees-web.xml file which is saved in the source repo (or as a self documentation method).

You can reference application config parameters (with the ${config_param} syntax) in the cloudbees-web.xml to avoid having sensitive values saved in your source repo.

The cloudbees-web.xml offers more options to define parameters but is specific to java stacks like EE app server stacks.

Sometimes it is preferable not to have all parameters embedded directly in the application archive file for various reasons:

• separation of code and sensitive information such as credentials
• for open source project to avoid bundling parameters into public repositories
• for continuous integration setup
• for security reason (encryption of sensitive information)

And thus you can parametrise this with environment variables as shown below.

Note that the cloudbees-web.xml is only in use for the current tomcat and jboss containers - other options for other containers will be provided. You are NOT REQUIRED to use a cloudbees-web.xml at all if you do not wish to. Many people will not need to - for example - for a database - you can use "bees app:bind" to bind to a database, and this will be made available as a data source to your container automatically.

An Example

Let's take a look at an example where database configuration credentials are defined as configuration parameters db.username and db.password and referenced in the cloudbees-web.xml file. Context parameter values can also reference configuration parameters (i.e. accessKey parameter using the “key” parameter)

An application deployed with this cloudbees-web.xml file is expecting to have three configuration parameters available at runtime (key, db.username, db.password)

To set these parameters for the app, we can use the bees config:set command.

The three bees commands above did the following:

• Set a global parameter (key) for all applications on the the account
• Set an app parameter (db.username) for the app with the ID "myappid"
• Deploy a WAR file using the ID, myappid, and set the db.password configuration parameter

After running these command, the app (myappid) would be deployed to CloudBees and the three configuration parameters will be made available at runtime for the app to use.

Accessing parameters from your app

By default, all configuration parameters are available to an application as Java System Properties.  Additionally, if your parameters are defined in the cloudbees-web.xml file using the ${param_name} syntax, then the parameter values will be injected into your application's configuration as appropriate at runtime.  For example, if you place the parameter as the value for a <context-param> element, it will be available to the application using ServletContext.getParameter(), etc.

If your application is deployed for multiple environments (ex: dev vs. test vs. prod), you can combine the use of these configuration parameters with the <environment> element in your cloudbees-web.xml file to switch around which values are injected into your app based on the environment flags it is deployed with.