open-liberty

Estimated reading time: 14 minutes

Official Open Liberty image.

GitHub repo: https://github.com/OpenLiberty/ci.docker

Library reference

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/open-liberty

Supported tags and respective `Dockerfile` links

Quick reference

Where to get help:
the Open Liberty community
Where to file issues:
https://github.com/OpenLiberty/ci.docker/issues
Maintained by:
the Open Liberty Community
Supported architectures: (more info)
amd64, i386, ppc64le, s390x
Published image artifact details:
repo-info repo’s repos/open-liberty/ directory (history)
(image metadata, transfer size, etc)
Image updates:
official-images PRs with label library/open-liberty
official-images repo’s library/open-liberty file (history)
Source of this description:
docs repo’s open-liberty/ directory (history)
Supported Docker versions:
the latest release (down to 1.6 on a best-effort basis)

Overview

The images in this repository contain Open Liberty. For more information about Open Liberty, see the Open Liberty Website site.

Image User

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 Open 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 COPY or ADD) have the correct permissions to be read and 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 read and executed by group 0, as well as any artifacts such as the application’s EAR or WAR file, JDBC driver, or other files that are placed on the image via COPY or ADD.

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 ADD or 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.

Usage

The images are designed to support a number of different usage patterns. The following examples assume that DefaultServletEngine.zip has been extracted to /tmp.

Each image contains a default server configuration that specifies the corresponding features and exposes ports 9080 and 9443 for HTTP and HTTPS respectively. A .WAR file can therefore 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 \
    open-liberty:webProfile8
```
When the server is started, you can browse to http://localhost/Sample1/SimpleServlet on the Docker host.
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.
```
$ docker run -d -p 80:9080 \
  -v /tmp/DefaultServletEngine:/config \
  open-liberty:webProfile8-sfj
```
You can also build an application layer on top of this image by using either the default server configuration or a new server configuration. In this example, we have copied the Sample1.war from /tmp/DefaultServletEngine/dropins to the same directory as the following Dockerfile.
```
FROM open-liberty:webProfile8
COPY Sample1.war /config/dropins/
```
This can then be built and run as follows:
```
$ docker build -t app .
$ docker run -d -p 80:9080 -p 443:9443 app
```
You can mount a data volume container that contains the application and the server configuration on to the image. This has the benefit that it has no dependency on files from the host but still allows the application container to be easily re-mounted on a newer version of the application server image. This example assumes that you have copied the /tmp/DefaultServletEngine directory in to the same directory as the Dockerfile.

Build and run the data volume container:
```
FROM open-liberty:webProfile8
COPY DefaultServletEngine /config
```
```
$ docker build -t app-image .
$ docker run -d -v /config \
    --name app app-image true
```
Run the Open Liberty image with the volumes from the data volume container mounted:
```
$ docker run -d -p 80:9080 \
  --volumes-from app open-liberty:webProfile8
```

Using `springBoot` images

The 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 /tmp directory.

A Spring Boot application JAR deploys to the dropins/spring directory within the default server configuration, not the dropins directory. 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 \
    open-liberty:springBoot2
```
Similarly, you can create a Spring Boot application layer over this image by adding the application JAR to the dropins/spring directory. In this example we copied hellospringboot.jar from /tmp to the same directory containing the following Dockerfile.
```
FROM open-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
```
The springBoot images provide the library cache directory, lib.index.cache, which contains an indexed library cache created by the springBootUtility command. Use lib.index.cache to provide the library cache for a thin application.

For example, run the following command to thin the hellospringboot.jar application.
```
$ <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 \
    open-liberty:springBoot2
```
Similarly, you can use the springBootUtility command to create thin application and library cache layers over a springBoot image. 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 open-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 open-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

When an open-liberty image starts, it can generate a Liberty server XML snippet in /config/configDropins/defaults/keystore.xml that specifies a keyStore stanza with a generated password. This causes Open Liberty to generate a default keystore and truststore with a self-signed certificate when it starts. Images can request this by setting:

ENV KEYSTORE_REQUIRED "true"

When providing your own keystore/truststore, this default behavior can be disabled by adding:

ENV KEYSTORE_REQUIRED "false"

It is good practice to place the keystore customization in /config/configDropins/defaults/keystore.xml even when not generated since this makes it easier to find and makes moving to the websphere-liberty docker image simpler.

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/ol/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/open-liberty/classCache as follows:

docker run -d -p 80:9080 -p 443:9443 \
    -v /tmp/open-liberty/classCache:/opt/ol/wlp/output/.classCache app

Or, create a named data volume container that exposes a volume at the location of the shared file:

docker run -v /opt/ol/wlp//output/.classCache \
    --name classcache open-liberty true

Then, run the Open 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 Open Liberty in read-only mode

Liberty writes to two different directories when running: /opt/ol/wlp//output and /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/ol/wlp//output --tmpfs /logs -v /config --read-only \
    open-liberty:webProfile8

Relationship between Open Liberty and WebSphere Liberty

WebSphere Liberty is a commercial distribution of Open Liberty. There is an official docker image for websphere-liberty. The websphere-liberty docker image predates the open-liberty one, so to make it simpler to move from open-liberty to websphere-liberty (or vice versa) the images are broadly compatible. It should be possible to move from one to the other with a simple FROM clause change. Some considerations for moving between them:

Open Liberty installs into `/opt/ol` rather than `/opt/ibm`.
Use the `/config` folder for accessing the server configuration.
Use the `/output` folder for accessing the server output.
When adding your own SSL configuration use the `/config/configDropins/defaults/keystore.xml`.

License

View license information for the software contained in this 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 repo-info repository’s open-liberty/ directory.

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.

Rate this page: