Chapter 2. Installation and Configuration

2.1. Overview

Before installing the JBoss EAP xPaaS image on your OpenShift instance, you must first determine whether you are installing the EAP xPaaS image in a production or a non-production environment. Production environments require Secure Sockets Layer (SSL) encryption for network communication for general public access, which is also known as a HTTPS connection. In this case you must use a signed certificate from a Certificate Authority (CA).

However, if you are installing the EAP xPaaS image for demonstration purposes, proof-of-concept (POC) designs, or environments with internal access only, unencrypted and insecure communication may be sufficient. The instructions referenced here describe how to create the required keystore for the xPaaS EAP image with a self-signed or a purchased SSL certificate.

Warning

Using a self-signed SSL certificate to create a keystore is not intended for production environments. For production environments or where SSL encrypted communication is required, you must use a SSL certificate that is purchased from a verified CA.

2.2. Key Terms

The following table describes the various terms that are used within the context of this topic.

Table 2.1. Terminology used in this topic

Key termDescription

SSL

Secure Sockets Layer encrypts network traffic between the client and the EAP web server, providing a HTTPS connection between them.

HTTPS

HTTPS is a protocol that provides an SSL-encrypted connection between a client and a server.

Keystore

A Java keystore is a repository to store SSL/TLS certificates and distribute them to applications for encrypted communication.

Secrets

A secret contains the Java keystore that gets passed to the EAP xPaaS image along with a password to access it. This then gets used in scripts to configure HTTPS access.

2.3. Initial Setup

The instructions in this guide follow on from and assume an OpenShift instance similar to that created in the OpenShift Primer.

2.4. Getting Started

After you have completed the Section 2.3, “Initial Setup” instructions, this topic helps you get started with the JBoss xPaaS EAP image by performing the required preliminary steps before you can install the image on OpenShift. This process consists of the following steps:

  • Step 1: Create project
  • Step 2: Create service account
  • Step 3: Create keystore from SSL certificate
  • Step 4: Create secret from keystore
  • Step 5: Add secret to service account
  • Step 6: Create and deploy EAP application

The following instructions describe how to perform each step.

Step 1: Create a new project in OpenShift

A project allows a group of users to organize and manage content separately from other groups. Create a project in OpenShift with the following command. 

$ oc create project <project-name>

You can then make this new project to be the current project with the following command: 

$ oc project <project-name>

Step 2: Create an EAP service account in your project

Service accounts are API objects that exist within each project. Create a service account named eap-service-account in the OpenShift project that you created in step 1. For the EAP 7 image specify the service account name to be eap7-service-account. 

$ oc create serviceaccount eap-service-account -n <project-name>

After creating the service account, configure the access permissions for it with the following command, specifying the correct name depending on the EAP image version. 

$ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):eap-service-account -n $(oc project -q)
Note

The service account that you create must be configured with the correct permissions with the ability to view pods in Kubernetes. This is required in order for clustering with the xPaaS EAP image to work. You can view the top of the log files to see whether the correct service account permissions have been configured.

Step 3: Create a keystore from SSL certificate

The xPaaS EAP image requires a keystore to be imported to properly install and configure the image on your OpenShift instance. Note that self-signed certificates do not provide secure communication and are intended for internal testing purposes.

Warning

For production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS).

See Generate a SSL Encryption Key and Certificate for more information on how to create a keystore with self-signed or purchased SSL certificates.

Step 4: Create a secret from the keystore

Next, create a secret from the keystore that you created in step 1 with the following command. 

$ oc secret new <secret-name> <keystore-filename>.jks

Step 5: Add the secret to your service account

Now add the secret created in step 3 to the eap-service-account that was created in step 2. You can do this with the following command. 

$ oc secrets add serviceaccount/eap-service-account secret/<secret-name>

Step 6: Create and deploy the EAP application

You can now create an EAP application using the defined image, or you can use the basic S2I template.

To create an EAP application using the defined image, run the following command. 

$ oc new-app <jboss-eap-7/eap70-openshift>

Alternatively, you can create an EAP application using the basic S2I template with the following command. 

$ oc new-app <eap7-basic-s2i>

2.5. Configuring the xPaaS EAP Image

The recommended method to run and configure the xPaaS JBoss EAP image is to use the OpenShift S2I process together with the application template parameters and environment variables.

Note

The variable EAP_HOME is used to denote the path to the JBoss EAP installation. Replace this variable with the actual path to your JBoss EAP installation.

The S2I process for the xPaaS JBoss EAP image works as follows:

  1. If a pom.xml file is present in the source repository, a Maven build process is triggered that uses the contents of the $MAVEN_ARGS environment variable. Although you can specify arguments or options with the $MAVEN_ARGS environment variable, Red Hat recommends that you use the $MAVEN_ARGS_APPEND environment variable to do this. The $MAVEN_ARGS_APPEND variable takes the default arguments from $MAVEN_ARGS and appends the options from $MAVEN_ARGS_APPEND to it. By default, the OpenShift profile uses the Maven package goal which includes system properties for skipping tests (-DskipTests) and enabling the Red Hat GA repository (-Dcom.redhat.xpaas.repo). The results of a successful Maven build are copied to EAP_HOME/standalone/deployments. This includes all JAR, WAR, and EAR files from the source repository specified by the $ARTIFACT_DIR environment variable. The default value of $ARTIFACT_DIR is the target directory.
  2. EAP_HOME/standalone/deployments is the artifacts directory, which is specified with the $ARTIFACT_DIR environment variable.
  3. All files in the configuration source repository directory are copied to EAP_HOME/standalone/configuration. If you want to use a custom JBoss EAP configuration file, it should be named standalone-openshift.xml.
  4. All files in the modules source repository directory are copied to EAP_HOME/modules.