This project contains the Dockerfiles for WebSphere Application Server Liberty.
According to Docker's best practices you should create a new image (FROM websphere-liberty) which adds a single application and the corresponding configuration. You should avoid configuring the image manually, after it started (unless it is for debugging purposes), because such changes won't be present if you spawn a new container from the image.
Even if you docker save the manually configured container, the steps to reproduce the image from websphere-liberty
will be lost and you will hinder your ability to update that image.
The key point to take-away from the sections below is that your application Dockerfile should always follow a pattern similar to:
FROM websphere-liberty:kernel
# Add my app and config
COPY --chown=1001:0 Sample1.war /config/dropins/
COPY --chown=1001:0 server.xml /config/
# Optional functionality
ARG SSL=true
ARG MP_MONITORING=true
# This script will add the requested XML snippets and grow image to be fit-for-purpose
RUN configure.sh
This will result in a Docker image that has your application and configuration pre-loaded, which means you can spawn new fully-configured containers at any time.
This section describes the optional enterprise functionality that can be enabled via the Dockerfile during build
time, by setting particular build-arguments (ARG
) and calling RUN configure.sh
. Each of these options trigger the inclusion of specific configuration via XML snippets, described below:
HTTP_ENDPOINT
- Decription: Add configuration properties for an HTTP endpoint.
- XML Snippet Location: http-ssl-endpoint.xml when SSL is enabled. Otherwise http-endpoint.xml
MP_HEALTH_CHECK
- Decription: Check the health of the environment using Liberty feature
mpHealth-1.0
(implements MicroProfile Health). - XML Snippet Location: mp-health-check.xml
- Decription: Check the health of the environment using Liberty feature
MP_MONITORING
- Decription: Monitor the server runtime environment and application metrics by using Liberty features
mpMetrics-1.1
(implements Microprofile Metrics) andmonitor-1.0
. - XML Snippet Location: mp-monitoring.xml
- Note: With this option,
/metrics
endpoint is configured without authentication to support the environments that do not yet support scraping secured endpoints.
- Decription: Monitor the server runtime environment and application metrics by using Liberty features
SSL
- Decription: Enable SSL in Liberty by adding the
ssl-1.0
feature. - XML Snippet Location: ssl.xml.
- Decription: Enable SSL in Liberty by adding the
IIOP_ENDPOINT
- Decription: Add configuration properties for an IIOP endpoint.
- XML Snippet Location: iiop-ssl-endpoint.xml when SSL is enabled. Otherwise, iiop-endpoint.xml.
- Note: If using this option,
env.IIOP_ENDPOINT_HOST
environment variable should be set to the server's host. See IIOP endpoint configuration for more details.
JMS_ENDPOINT
- Decription: Add configuration properties for an JMS endpoint.
- XML Snippet Location: jms-ssl-endpoint.xml when SSL is enabled. Otherwise, jms-endpoint.xml
OIDC
- Decription: Enable OpenIdConnect Client function by adding the
openidConnectClient-1.0
feature. - XML Snippet Location: oidc.xml
- Decription: Enable OpenIdConnect Client function by adding the
OIDC_CONFIG
- Decription: Enable OpenIdConnect Client configuration to be read from environment variables.
- XML Snippet Location: oidc-config.xml
- Note: The following variables will be read: OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_DISCOVERY_URL.
The Liberty session caching feature builds on top of an existing technology called JCache (JSR 107), which provides an API for distributed in-memory caching. There are several providers of JCache implementations. One example is Hazelcast In-Memory Data Grid. Enabling Hazelcast session caching retrieves the Hazelcast client libraries from the hazelcast/hazelcast Docker image, configures Hazelcast by copying a sample hazelcast.xml, and configures the Liberty server feature sessionCache-1.0 by including the XML snippet hazelcast-sessioncache.xml. By default, the Hazelcast Discovery Plugin for Kubernetes will auto-discover its peers within the same Kubernetes namespace. To enable this functionality, the Docker image author can include the following Dockerfile snippet, and choose from either client-server or embedded topology.
### Hazelcast Session Caching ###
# Copy the Hazelcast libraries from the Hazelcast Docker image
COPY --from=hazelcast/hazelcast --chown=1001:0 /opt/hazelcast/lib/*.jar /opt/ibm/wlp/usr/shared/resources/hazelcast/
# Instruct configure.sh to copy the client topology hazelcast.xml
ARG HZ_SESSION_CACHE=client
# Instruct configure.sh to copy the embedded topology hazelcast.xml and set the required system property
#ARG HZ_SESSION_CACHE=embedded
#ENV JAVA_TOOL_OPTIONS="-Dhazelcast.jcache.provider.type=server ${JAVA_TOOL_OPTIONS}"
## This script will add the requested XML snippets and grow image to be fit-for-purpose
RUN configure.sh
For issues relating specifically to the Dockerfiles and scripts, please use the GitHub issue tracker. For more general issue relating to IBM WebSphere Application Server Liberty you can get help through the WASdev community or, if you have production licenses for WebSphere Application Server, via the usual support channels. We welcome contributions following our guidelines.
The Dockerfiles and associated scripts found in this project are licensed under the Apache License 2.0.