Appendix A. S2I scripts and Maven

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

A.1. Maven artifact repository mirrors and JWS for OpenShift

A Maven repository holds build artifacts and dependencies, such as the project Java archive (JAR) files, library JAR files, plugins or any other project-specific artifacts. A Maven repository also defines locations that you can download artifacts from while performing the source-to-image (S2I) build. In addition to using the Maven Central Repository, some organizations also deploy a local custom repository (mirror).

A local mirror provides the following benefits:

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

A Maven repository manager can serve as local cache to a mirror. If the repository manager is already deployed and can be reached externally at a specified URL location, the S2I build can use this repository. You can use an internal Maven repository by adding the MAVEN_MIRROR_URL environment variable to the build configuration of the application.

Additional resources

A.1.1. Using an internal Maven repository for a new build configuration

You can add the MAVEN_MIRROR_URL environment variable to a new build configuration of your application, by specifying the --build-env option with the oc new-app command or the oc new-build command.

Procedure

  1. Enter the following command: 

    $ oc new-app \
 https://github.com/web-servers/tomcat-websocket-chat-quickstart.git#main \
 --image-stream=jboss-webserver57-openjdk8-tomcat9-openshift-ubi8:latest \
 --context-dir='tomcat-websocket-chat' \
 --build-env MAVEN_MIRROR_URL=http://10.0.0.1:8080/repository/internal/ \
 --name=jws-wsch-app
    Note

    The preceding command assumes that the repository manager is already deployed and can be reached at http://10.0.0.1:8080/repository/internal/.

A.1.2. Using an internal Maven repository for an existing build configuration

You can add the MAVEN_MIRROR_URL environment variable to an existing build configuration of your application, by specifying the name of the build configuration with the oc set env command.

Procedure

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

    $ oc get bc -o name

    The preceding command produces the following type of output: 

    buildconfig/jws
    Note

    In the preceding example, jws is the name of the build configuration.

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

    $ oc set 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 set 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 by using oc start-build
Note

During the application build process, Maven dependencies are downloaded from the repository manager rather than from the default public repositories. When the build process is completed, the mirror contains all the dependencies that are retrieved and used during the build process.

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

The Red Hat JBoss Web Server for OpenShift image includes scripts to run Catalina and to use Maven to create and deploy the .war package.

run
Runs Catalina (Tomcat)
assemble
Uses Maven to build the web application source, create the .war file, and move the .war file to the $JWS_HOME/tomcat/webapps directory.

A.3. JWS for OpenShift datasources

JWS for OpenShift provides three type of data sources:

Default internal data sources
PostgreSQL, MySQL, and MongoDB data sources are available on OpenShift by default through the Red Hat Registry. These data sources do not require additional environment files to be configured for image streams. To enable a database to be discovered and used as a data source, you can set the DB_SERVICE_PREFIX_MAPPING environment variable to the name of the OpenShift service.
Other internal data sources
These data sources are run on OpenShift but they are not available by default through the Red Hat Registry. Environment files that are added to OpenShift Secrets provide configuration of other internal data sources.
External data sources
These data sources are not run on OpenShift. Environment files that are added to OpenShift Secrets provide configuration of external data sources.

ENV_FILES property

You can add the environment variables for data sources to the OpenShift Secret for the project. You can use the ENV_FILES property to call these environment files within the template.

DB_SERVICE_PREFIX_MAPPING environment variable

Data sources are automatically created based on the value of certain environment variables. The DB_SERVICE_PREFIX_MAPPING environment variable defines JNDI mappings for the data sources.

The allowed value for the DB_SERVICE_PREFIX_MAPPING variable is a comma-separated list of POOLNAME-DATABASETYPE=PREFIX triplets. Each triplet consists of the following values:

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

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

Additional resources

A.4. JWS for OpenShift compatible environment variables

You can modify the build configuration by including environment variables with the source-to-image (S2I) build command. For more information, see Maven artifact repository mirrors and JWS for OpenShift.

The following table lists the valid environment variables for the Red Hat JBoss Web Server for OpenShift images:

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

SOURCE_REPOSITORY_URL

Git Repository URL

Git source URI for Application

https://github.com/web-servers/tomcat-websocket-chat-quickstart.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/