Chapter 5. Reference

5.1. Source-to-Image (S2I)

The Red Hat JBoss Web Server for OpenShift image includes S2I scripts and Maven.

5.1.1. Using maven artifact repository mirrors with JWS for OpenShift

A Maven repository holds build artifacts and dependencies, such as the project jars, library jars, plugins or any other project specific artifacts. It also defines locations to download artifacts from while performing the S2I build. Along with using the Maven Central Repository, some organizations also deploy a local custom repository (mirror).

Benefits of using a local mirror are:

  • Availability of a synchronized mirror, which is geographically closer and faster.
  • Greater control over the repository content.
  • Possibility to share artifacts across different teams (developers, CI), without the need to rely on public servers and repositories.
  • Improved build times.

A Maven repository manager can serve as local cache to a mirror. Assuming that the repository manager is already deployed and reachable externally at http://10.0.0.1:8080/repository/internal/, the S2I build can use this repository. To use an internal Maven repository, add the MAVEN_MIRROR_URL environment variable to the build configuration of the application.

For a new build configuration, use the --build-env option with oc new-app or oc new-build: 

$ oc new-app \
 https://github.com/jboss-openshift/openshift-quickstarts.git#master \
 --image-stream=jboss-webserver<version>-openjdk8-tomcat9-openshift-rhel8:latest\*
 --context-dir='tomcat-websocket-chat' \
 --build-env MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/ \
 --name=jws-wsch-app

For an existing build configuration:

  1. Identify the build configuration which requires the MAVEN_MIRROR_URL variable: 

    $ oc get bc -o name

buildconfig/jws

  2. Add the MAVEN_MIRROR_URL environment variable to buildconfig/jws: 

    $ oc env bc/jws MAVEN_MIRROR_URL="http://10.0.0.1:8080/repository/internal/"

buildconfig "jws" updated

  3. Verify the build configuration has updated: 

    $ oc env bc/jws --list

# buildconfigs jws
MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/
  4. Schedule a new build of the application using oc start-build
Note

During application build, Maven dependencies are download from the repository manager, instead of the default public repositories. Once the build has finished, the mirror contains all the dependencies retrieved and used during the build.

5.1.2. Scripts included on the Red Hat JBoss Web Server for OpenShift image

run
runs Catalina (Tomcat)
assemble
uses Maven to build the source, create package (.war) and move it to the $JWS_HOME/tomcat/webapps directory.

5.1.3. JWS for OpenShift datasources

There are 3 types of data sources:

  1. Default Internal Datasources: These are PostgreSQL, MySQL, and MongoDB. These datasources are available on OpenShift by default through the Red Hat Registry and do not require additional environment files to be configured for image streams. To make a database discoverable and used as a datasource, set the DB_SERVICE_PREFIX_MAPPING environment variable to the name of the OpenShift service.
  2. Other Internal Datasources: These are datasources not available by default through the Red Hat Registry but run on OpenShift. Configuration of these datasources is provided by environment files added to OpenShift Secrets.
  3. External Datasources: Datasources not run on OpenShift.Configuration of external datasources is provided by environment files added to OpenShift Secrets.

The datasources environment files are added to the OpenShift Secret for the project. These environment files are then called within the template using the ENV_FILES environment property.

Datasources are automatically created based on the value of certain environment variables.The most important environment variable is DB_SERVICE_PREFIX_MAPPING. DB_SERVICE_PREFIX_MAPPING defines JNDI mappings for the datasources. The allowed value for this variable is a comma-separated list of POOLNAME-DATABASETYPE=PREFIX triplets, where:

  • POOLNAME is used as the pool-name in the datasource.
  • DATABASETYPE is the database driver to use.
  • PREFIX is the prefix used in the names of environment variables that are used to configure the datasource.

For each POOLNAME-DATABASETYPE=PREFIX triplet defined in the DB_SERVICE_PREFIX_MAPPING environment variable, the launch script creates a separate datasource, which is executed when running the image.

For a full listing of datasource configuration environment variables, please see the Datasource Configuration Environment Variables list given here.

5.1.4. JWS for OpenShift compatible environment variables

The build configuration can be modified by including environment variables to the Source-to-Image build command (see Section 5.1.1, “Using maven artifact repository mirrors with JWS for OpenShift”). The valid environment variables for the Red Hat JBoss Web Server for OpenShift images are:

Variable NameDisplay NameDescriptionExample Value

ARTIFACT_DIR

N/A

.war, .ear, and .jar files from this directory will be copied into the deployments directory

target

APPLICATION_NAME

Application Name

The name for the application

jws-app

CONTEXT_DIR

Context Directory

Path within Git project to build; empty for root project directory

tomcat-websocket-chat

GITHUB_WEBHOOK_SECRET

Github Webhook Secret

Github trigger secret

Expression from: [a-zA-Z0-9]{8}

GENERIC_WEBHOOK_SECRET

Generic Webhook Secret

Generic build trigger secret

Expression from: [a-zA-Z0-9]{8}

HOSTNAME_HTTP

Custom HTTP Route Hostname

Custom hostname for http service route. Leave blank for default hostname

<application-name>-<project>.<default-domain-suffix>

HOSTNAME_HTTPS

Custom HTTPS Route Hostname

Custom hostname for https service route. Leave blank for default hostname

<application-name>-<project>.<default-domain-suffix>

IMAGE_STREAM_NAMESPACE

Imagestream Namespace

Namespace in which the ImageStreams for Red Hat Middleware images are installed

openshift

JWS_HTTPS_SECRET

Secret Name

The name of the secret containing the certificate files

jws-app-secret

JWS_HTTPS_CERTIFICATE

Certificate Name

The name of the certificate file within the secret

server.crt

JWS_HTTPS_CERTIFICATE_KEY

Certificate Key Name

The name of the certificate key file within the secret

server.key

JWS_HTTPS_CERTIFICATE_PASSWORD

Certificate Password

The Certificate Password

P5ssw0rd

JWS_ADMIN_USERNAME

JWS Admin Username

JWS Admin account username

ADMIN

JWS_ADMIN_PASSWORD

JWS Admin Password

JWS Admin account password

P5sw0rd

SOURCE_REPOSITORY_URL

Git Repository URL

Git source URI for Application

https://github.com/jboss-openshift/openshift-quickstarts.git

SOURCE_REPOSITORY_REFERENCE

Git Reference

Git branch/tag reference

1.2

IMAGE_STREAM_NAMESPACE

Imagestream Namespace

Namespace in which the ImageStreams for Red Hat Middleware images are installed

openshift

MAVEN_MIRROR_URL

Maven Mirror URL

URL of a Maven mirror/repository manager to configure.

http://10.0.0.1:8080/repository/internal/

5.2. Valves on JWS for OpenShift

5.2.1. JWS for OpenShift compatible environmental variables (valve component)

You can define the following environment variables to insert the valve component into the request processing pipeline for the associated Catalina container.

Variable NameDescriptionExample ValueDefault Value

ENABLE_ACCESS_LOG

Enable the Access Log Valve to log access messages to the standard output channel.

true

false

5.3. Checking logs

To view the OpenShift logs or the logs provided by a running container’s console: 

$ oc logs -f <pod_name> <container_name>

Access logs are stored in /opt/jws-5.5/tomcat/logs/.