Using CLI in JBoss EAP on OpenShift

Vijay Chintalapati bio photo By Vijay Chintalapati Comment

Why CLI ?

Have you ever tried modifying a EAP standalone.xml by hand? If you did, you may have run into, more than once, the issue of missing or adding something unintended resulting in a stacktrace when attempting to start the server. For the very same reason, it is higly recommended that one either use the Management Console or use JBoss CLI (Command Line Interface) to modfiy the server configuration.

The same challenge exists for EAP on OpenShift as well. Referring to official documentation, under Other Tips it is clearly stated:

standalone.xml can be found in the {git repo}/.openshift/config/ directory. Please be careful when making a change to the file. Also, make sure the EAP server restarts after making the change.

How to use CLI in OpenShift ?

Using port-forwarding and a local EAP installation for access to CLI

Enable port-forwarding by running the following command (replace with name of your application):

rhc port-forward <app-name>

Once port-forwarding is enabled, run the following command to connect to the management port of remote EAP instance:

# $JBOSS_HOME points to the folder where the JBoss EAP was locally installed 
$JBOSS_HOME/bin/ --connect

Using CLI tools inside the OpenShift EAP application

Instructions to use CLI in this way are provided here

Managed vs Unmanaged Server Configuration

When CLI is used on EAP outside of OpenShift, any updates to the configuration gets immediately persisted to the standalone.xml file and hence the changes survive a restart of the application.

In OpenShift however, by default, the changes made via CLI or the web management console get persisted to a different copy of standalone.xml and not the one that is in the git repo. As a result with any restart, the configuration is read from the file in the git and the changes saved in the other copy is lost forever. That is to say the server is running in Managed mode.

To change this default behavior such that the EAP always uses the copy of configuration file where it persisted the changes and essentially ignore the configuration file in the git repo, one can run the following command:

rhc set-env DISABLE_OPENSHIFT_MANAGED_SERVER_CONFIG=true --app <app-name>

With the above setting, in Unmanaged mode, you can now modify the server configuration with CLI and retain the changes across restarts.


For introduction to application scaling refer to this documentation.

Scaling uses the git repo to setup a new gear as mentioned in the official documentation:

OpenShift checks that you have a free gear (out of your remaining account gears) and then creates another copy of your web cartridge on that new gear. The code in the git repository is copied to each new gear, but the data directory begins empty. When the new cartridge copy starts it will invoke your build hooks and then the HAProxy will begin routing web requests to it. If you push a code change to your web application all of the running gears will get that update.

Hence, using the Unmanaged mode does not really help when the application needs to scale.

So how can one:

  1. Use the CLI to make all the necessary changes to configuration, incrementally or otherwise
  2. And at the end of all changes make them permanent in git repo for scaling to correctly work ?

The workaround that I can think of is to get the copy of the standalone.xml from the application where the changes are persisted and overwrite the one in local git repository, commit and push the changes.

For example: In a new JBoss EAP application, remove the H2DS datasource.

# Create a new JBoss EAP app by the name jbosseap
rhc app-create jbosseap jbosseap-6

# SSH into jbosseap application
rhc ssh jbosseap

# Once in the application, use JBoss CLI -c --controller=\

# In the CLI mode remove the data source with the name : H2DS 
data-source --name=H2DS remove

# Quit CLI and exit SSH

# Get the copy of standalone.xml and apply it to the local git repo one
# Run the command while in the root folder of the local git repo
# The userid@application-url is the same as what gets displayed on the first 
# line when you do : rhc ssh jbosseap 
scp userid@application-url:jbosseap/standalone/configuration/standalone.xml \

# Add the change, commit and push from the root folder of the application
git add .openshift/config/standalone.xml
git commit -m "Removed H2DS from the server configuration"
git push

# Port forward and verify the application at
rhc port-forward jbosseap


One can still use JBoss CLI to make changes to the EAP on OpenShift and use the traditional secure copy to persist the changes to the git repo.

Please do share if you have other ideas or found a way to do this without a workaround.

comments powered by Disqus