websphere-libertyEstimated reading time: 16 minutes
Official IBM WebSphere Application Server for Developers Liberty image.
GitHub repo: https://github.com/WASdev/ci.docker
This content is imported from the official Docker Library docs, and is provided by the original uploader. You can view the Docker Hub page for this image at https://hub.docker.com/images/websphere-liberty
Supported tags and respective
Where to get help:
the WASdev community
Where to file issues:
the IBM WASdev Community
Published image artifact details:
(image metadata, transfer size, etc)
Supported Docker versions:
the latest release (down to 1.6 on a best-effort basis)
The images in this repository contain IBM WebSphere Application Server Liberty for Developers and the IBM Java Runtime Environment. See the license section below for restrictions relating to the use of this image. For more information about WebSphere Application Server Liberty, see the WASdev site.
This image runs by default with
USER 1001 (non-root), as part of group
0. Please make sure you read below to set the appropriate folder and file permissions.
Updating folder permissions
All of the folders accessed by WebSphere Liberty have been given the appropriate permissions, but if your extending Dockerfile needs permission to another location you can simply temporarily switch into root and provide the needed permissions, example:
USER root RUN mkdir -p /myFolder && chown -R 1001:0 /myFolder USER 1001
Updating file permissions
You have to make sure that all the artifacts you are copying into the image (via
ADD) have the correct permissions to be
executed by user
1001 or group
0, because the ownership of the file is changed to be
root:0 when transferring into the docker image.
You have a few options for doing this: before copying the file, during copy, or after copy.
Updating permissions before copying
Since the ownership of the file will change to
root:0, you can simply set the permissions for the owner’s group to be able to read/execute the artifact (i.e. the middle digit of a
chmod command). For example, you can do
chmod g+rx server.xml to ensure your
server.xml can be
executed by group
0, as well as any artifacts such as the application’s
WAR file, JDBC driver, or other files that are placed on the image via
Updating permissions during copy
If you’re using Docker v17.09.0-ce and newer you can take advantage of the flag
--chown=<user>:<group> during either
COPY. For example:
COPY --chown=1001:0 jvm.options /config/jvm.options. This is the preferred approach as you don’t need to worry about changing permissions before calling
docker build and you also do not duplicate layers in the resulting image.
Updating permissions after copy
If you need your Dockerfile to work with older versions of Docker CE and don’t want to pre-process the permissions of the files you can temporarily switch into root to change the permissions of the needed files. For example:
USER root RUN chown 1001:0 /config/jvm.options RUN chown 1001:0 /output/resources/security/ltpa.keys USER 1001
Please note that this pattern will duplicate the docker layers for those artifacts, which can heavily bloat your resulting docker image (depending on the size of the artifact). So it is recommended to set the permissions before or during copy.
There are multiple tags available in this repository. The image with the tag
beta contains the contents of the install archive for the latest monthly beta. The other images are all based on the latest generally available fix pack.
kernel image contains just the Liberty kernel and no additional runtime features. This image can be used as the basis for custom built images that contain only the features required for a specific application. For example, the following Dockerfile starts with this image, copies in the
server.xml that lists the features required by the application, and then uses the
installUtility command to download those features from the online repository.
FROM websphere-liberty:kernel COPY --chown=1001:0 Sample1.war /config/dropins/ COPY --chown=1001:0 server.xml /config/ RUN installUtility install --acceptLicense defaultServer
webProfile8 image contains the features required for Java EE8 Web Profile compliance. The
javaee8 image extends this image and adds the features required for Java EE8 Full Platform compliance. The
javaee8 image is also tagged with
webProfile7 image contains the features required for Java EE7 Web Profile compliance. The
javaee7 image extends this image and adds the features required for Java EE7 Full Platform compliance.
javaee7 images also contain a common set of features that are expected to be of use for a typical production scenario. These features are:
microProfile2 images contains the features required to support MicroProfile 1.4 and MicroProfile 2.0 (respectively).
springBoot2 images contain all features required for running Spring Boot 1.5 and 2.0 applications; including
springBoot-2.0, respectively, plus
The images are designed to support a number of different usage patterns. The following examples are based on the Java EE8 Liberty application deployment sample and assume that DefaultServletEngine.zip has been extracted to
/tmp and the
server.xml updated to accept HTTP connections from outside of the container by adding the following element inside the
server stanza (if not using one of the pre-packaged
server.xml files with our tags):
<httpEndpoint host="*" httpPort="9080" httpsPort="-1"/>
It is a very strong best practice to create an extending Docker image, we called it the
application image, that encapsulates an application and its configuration. This creates a robust, self-contained and predictable Docker image that can span new containers upon request, without relying on volumes or other external runtime artifacts that may behave different over time.
If you want to build the smallest possible WebSphere Liberty application image you can start with our
kernel tag, add your artifacts, and run
installUtility to grow the set of features to be fit-for-purpose. Scroll up to the
Tags section for an example.
If you want to start with one of the pre-packaged tags you do not need to run
installUtility if the tag contains all the features you required, and you may not even need to copy a
server.xml - unless you have updates you want to make. So one example of building an application image that runs a MicroProfile 2.0 application is:
FROM websphere-liberty:microprofile2 COPY --chown=1001:0 Sample1.war /config/dropins/
You can then build and run this image:
$ docker build -t app . $ docker run -d -p 80:9080 -p 443:9443 app
Using volumes for configuration
This pattern can be useful for quick experiments / early development (i.e.
I just want to run the application as I iterate over it), can should not be used for development scenarios that involve different teams and environments - for these cases the
Application Image pattern described above is the way to go.
volumes, an application file can be mounted in the
dropins directory of this server and run. The following example starts a container in the background running a .WAR file from the host file system with the HTTP and HTTPS ports mapped to 80 and 443 respectively.
$ docker run -d -p 80:9080 -p 443:9443 \ -v /tmp/DefaultServletEngine/dropins/Sample1.war:/config/dropins/Sample1.war \ websphere-liberty:webProfile8
When the server is started, you can browse to http://localhost/Sample1/SimpleServlet on the Docker host.
Note: If you are using the boot2docker virtual machine on OS X or Windows, you need to get the IP of the virtual host by using the command
boot2docker ip instead of by using localhost.
For greater flexibility over configuration, it is possible to mount an entire server configuration directory from the host and then specify the server name as a parameter to the run command. Note: This particular example server configuration provides only HTTP access.
```console $ docker run -d -p 80:9080 \ -v /tmp/DefaultServletEngine:/config \ websphere-liberty:webProfile8 ```
springBoot images introduce capabilities specific to the support of Spring Boot applications, including the
springBootUtility used to separate Spring Boot applications into thin applications and dependency library caches. To elaborate these capabilities this section assumes the standalone Spring Boot 2.0.x application
hellospringboot.jar exists in the
A Spring Boot application JAR deploys to the
dropins/springdirectory within the default server configuration, not the
dropinsdirectory. Liberty allows one Spring Boot application per server configuration. The following example starts a container running a Spring Boot application.
$ docker run -d -p 8080:9080 \ -v /tmp/hellospringboot.jar:/config/dropins/spring/hellospringboot.jar \ websphere-liberty:springBoot2
Similarly, you can create a Spring Boot application layer over this image by adding the application JAR to the
dropins/springdirectory. In this example we copied
/tmpto the same directory containing the following Dockerfile.
FROM websphere-liberty:springBoot2 COPY hellospringboot.jar /config/dropins/spring/
The custom image can be built and run as follows.
$ docker build -t app . $ docker run -d -p 8080:9080 app
springBootimages provide the library cache directory,
lib.index.cache, which contains an indexed library cache created by the
lib.index.cacheto provide the library cache for a thin application.
For example, run the following command to thin the
$ <wlp>/bin/springBootUtility thin \ --sourceAppPath=/tmp/hellospringboot.jar \ --targetLibCachePath=/tmp/lib.index.cache \ --targetThinAppPath=/tmp/thinhellospringboot.jar
You can run the thin application by mounting both the target application JAR and library cache when starting the container.
$ docker run -d -p 8080:9080 \ -v /tmp/thinhellospringboot.jar:/config/dropins/spring/thinhellospringboot.jar \ -v /tmp/lib.index.cache:/lib.index.cache \ websphere-liberty:springBoot2
Similarly, you can use the
springBootUtilitycommand to create thin application and library cache layers over a
springBootimage. The following example uses docker staging to efficiently build an image that deploys a fat Spring Boot application as two layers containing a thin application and a library cache.
FROM websphere-liberty:springBoot2 as staging COPY hellospringboot.jar /staging/myFatApp.jar RUN springBootUtility thin \ --sourceAppPath=/staging/myFatApp.jar \ --targetThinAppPath=/staging/myThinApp.jar \ --targetLibCachePath=/staging/lib.index.cache FROM websphere-liberty:springBoot2 COPY --from=staging /staging/lib.index.cache /lib.index.cache COPY --from=staging /staging/myThinApp.jar /config/dropins/spring/myThinApp.jar
For Spring Boot applications packaged with library dependencies that rarely change across continuous application updates, you can use the capabilities mentioned above to to share library caches across containers and to create even more efficient docker layers that leverage the docker build cache.
Providing your own keystore/truststore
By default, when a
websphere-liberty image starts, a Liberty server XML snippet is generated in
/config/configDropins/defaults/keystore.xml that specifies a
keyStore stanza with a generated password. This causes Liberty to generate a default keystore and truststore with a self-signed certificate when it starts (see the Knowledge Center for more information). When providing your own keystore/truststore, this default behavior can be disabled by ensuring that a file already exists at
/config/configDropins/defaults/keystore.xml (for example, added as part of your Docker build). This file can contain your keystore configuration or could just contain an empty
Using IBM JRE Class data sharing
The IBM JRE provides a feature Class data sharing which offers transparent and dynamic sharing of data between multiple Java Virtual Machines running on the same host by using shared memory backed by a file. When running the Liberty Docker image, it looks for the file at
/opt/ibm/wlp/output/.classCache. To benefit from Class data sharing, this location needs to be shared between containers either through the host or a data volume container.
Taking the application image from example 3 above, containers can share the host file location (containing the shared cache)
/tmp/websphere-liberty/classCache as follows:
docker run -d -p 80:9080 -p 443:9443 \ -v /tmp/websphere-liberty/classCache:/opt/ibm/wlp/output/.classCache app
Or, create a named data volume container that exposes a volume at the location of the shared file:
docker run -e LICENSE=accept -v /opt/ibm/wlp/output/.classCache \ --name classcache websphere-liberty true
Then, run the WebSphere Liberty image with the volumes from the data volume container classcache mounted as follows:
docker run -d -p 80:9080 -p 443:9443 --volumes-from classcache app
Running WebSphere Liberty in read-only mode
Liberty writes to two different directories when running:
/logs. In order to run the Liberty image in read-only mode these may be mounted as temporary file systems. If using the provided image, the keystore will be generated on initial start up in the server configuration. This means that the server configuration directory either needs to be read-write or the keystore will need to be built into the image. In the example command
/config is mounted as a read-write volume.
docker run -d -p 80:9080 -p 443:9443 \ --tmpfs /opt/ibm/wlp/output --tmpfs /logs -v /config --read-only \ websphere-liberty:javaee8
The base Ubuntu image does not include additional language packs. To use an alternative locale, build your own image that installs the required language pack and then sets the
LANG environment variable. For example, the following Dockerfile starts with the
websphere-liberty:webProfile8 image, installs the Portuguese language pack, and sets Brazilian Portuguese as the default locale:
FROM websphere-liberty:webProfile8 RUN apt-get update \ && apt-get install -y language-pack-pt-base \ && rm -rf /var/lib/apt/lists/* ENV LANG pt_BR.UTF-8
The Dockerfiles and associated scripts are licensed under the Apache License 2.0.
Licenses for the products installed within the images are as follows:
- IBM JRE (International License Agreement for Non-Warranted Programs)
- IBM WebSphere Application Server in the non-beta images ILAN (International License Agreement for Non-Warranted Programs).
- IBM WebSphere Application Server Liberty Beta in the
betaimage (International License Agreement for Early Release of Programs)
- Non IBM License
Note: These licenses do not permit further distribution and that the terms for WebSphere Application Server in the non-beta images restrict usage to a developer machine or build server only, or subject to a maximum 2 gigabyte heap usage across all instances. Instructions are available to enable entitled customers to upgrade the Docker Hub image for production use or build their own production licensed image.
As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).
Some additional license information which was able to be auto-detected might be found in the
As for any pre-built image usage, it is the image user’s responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.library, sample, websphere-liberty