Using Payara Server With Docker
Using Payara Server With Docker
Docker is an open-source tool used to create, deploy and manage small portable containers. Containers
are similar to virtual machines (VM), but where VMs run an entire operating system inside, the host
containers only package the required components. Because of this they are extremely lightweight;
they start up in a fraction of the time of a regular VM and waste very little extra resources on top of
the main process being run inside them. They are used primarily as a lightweight way to assure that
the program will run the same regardless of host platform. Docker can also manage virtual network-
ing between containers, as well as health checks, to make sure each container is running properly.
Payara provides several Docker container images that can be used as-is to run your applications on
Payara Server or Payara Micro (the Payara Platform). Or, you can create your own Docker images
based on the provided Payara Docker container images. This guide will demonstrate the basic usage
of Docker, as well as some example configurations using the Payara Server Docker images.
At the time of writing this guide, the most recent Payara Server release is 5.191. Some functionality
may differ if you’re using a different version.
Image An image is a snapshot of how a container should look before it starts up. It will
define which programs are installed, what the startup program will be, and which
ports will be exposed.
Container A container is an image at runtime. It will be running the process and the con-
figuration defined by the image, although the configuration may differ from the
image if any new commands have been run inside the container since startup.
Docker Daemon The Docker daemon is the service that runs on your host operating system.
Containers are run from the Docker daemon. The Docker CLI (command line
interface) just interacts with this process.
1
Using Payara Server with Docker
Tag A tag distinguishes multiple images within a repository from one another. Often
these tags correspond to specific versions. Because of this, when no tag is spec-
ified when running an image, the ‘latest’ tag is assumed.
Entrypoint The Entrypoint command is run when the container starts. Containers will exit as
soon as the entrypoint process terminates.
Installation of Docker
To run Docker containers, Docker must first be installed on your operating system. To install Docker,
you can follow the OS specific guide from the Docker documentation1.
In case your system is Microsoft Windows® or Mac®, download and run the installation program for
Docker Desktop according to the instructions.
1. Install the Docker program according to the instructions for your Linux® distribution.
2. Start the Docker daemon - this is specific to your Linux distribution. On Ubuntu®, you would
do it by sudo systemctl start docker.
3. By following the above steps, you will have Docker setup and ready to run. If however you
want to perform steps further to the basic installation such as: enabling Docker on boot,
running Docker without sudo, or allowing remote connections to your Docker daemon, then
the post-install guide on the Docker website2 details how to do these steps and more.
• After installing Docker on Linux, you need to run all Docker commands with sudo, e.g.
sudo docker info. To run Docker without sudo, add your user into a group called
docker and restart your computer.
2
Using Payara Server with Docker
Once you’ve got Docker installed, you can run the following command to verify your install (on Linux,
you might need to prepend the command with sudo):
This will run the ‘hello-world’ Docker container in the foreground, which is a minimal image with a
C program to print the message it does. Since the container then exits immediately, it won’t block
the terminal.
docker ps
Any container can be referenced in commands either by its ID directly, or one of its aliases listed on
the right. If none were specified on the command line, it’ll be assigned a random one.
If you don’t see anything from here, it means that no containers are running. If you expect to see
a process here but you don’t, it likely means it errored out and stopped, since Docker containers
terminate as soon as the entrypoint program exits. For scenarios like this, the Docker daemon use-
fully keeps containers stored after they’ve closed. You can run the following command to see all
containers, even after they’ve finished:
docker ps -a
This will also list stopped containers. To use a container with the same alias, these stopped containers
must be removed. See the Docker rm command later for details on how to do this.
3
Using Payara Server with Docker
Starting a Container
Using the hello-world image as a start point, we’ll start a container:
This runs the ‘hello-world’ container, assuming the latest tag. You can specify a custom tag by
appending the tag name after the image name, separating them with a colon. The container will run
in the foreground but since the process exits almost immediately it won’t block the terminal. If the
image isn’t found locally, it will be downloaded from DockerHub (as with the docker pull command).
The following parameters are common when running containers:
4
Using Payara Server with Docker
Basic Networking
When running a container, the -p option explained above maps a port on the host to a port on the
container being run. If no port mappings are specified the container is still accessible, but only from
the host running the Docker daemon. Docker handles a collection of networks; the default one is
named ‘bridge’, and will allow containers running on the same machine to communicate. You can
inspect this network by running the following command:
This will print out the details of the bridge network, and within that the IPs of containers running on
it. You can read more about Docker networking here: https://docs.docker.com/network/.
Stopping a Container
When you’ve got a container running and it’s visible in the output of docker ps, you can stop the
container using the following syntax:
This command will send a SIGTERM to the main process running inside the container in order to ter-
minate it. If the main process doesn’t handle SIGTERM signals properly, either because it’s hanging,
or it hasn’t been designed with that in mind, then a SIGKILL will be sent after a grace period (default
10 seconds) if the container hasn’t terminated.
If you need to forcibly stop a container, you can run the following command instead:
This command kills the container immediately with a SIGKILL. You can change the signal sent by
this command with the --signal option.
5
Using Payara Server with Docker
To fix this, the old container (that appears with docker ps -a) will need removing. You can remove
this container using it’s name or any aliases assigned to it like so:
docker rm <container-id/alias>
This will print out the current content of the container logs to the terminal. To follow these logs, add
the -f parameter. To see timestamps with the logs, use the -t parameter.
6
Using Payara Server with Docker
The command above will execute the given command on the given container. The -it options are
present if you specify the command as being `sh` for example. This makes the command interactive,
which allows an interactive shell process to be run inside the container.
FROM alpine:3.8
ENV test world
CMD echo "Hello $test!"
This image is built from the Alpine image (a minimal Linux distribution made for Docker), and will
print “Hello world!” when run. Dockerfiles will be written in the same format as above, using the
Dockerfile command specified at the beginning of any line. Some basic commands are covered below.
FROM
The FROM command specifies a base image for your custom image. As such it should usually be the
first command in your Dockerfile. Each image is expected to build from another, unless you want to
build every image you write from scratch7 (a 0 byte image that doesn’t even contain a filesystem).
The FROM command follows the following syntax:
FROM <image>[:<tag>]
If no tag is specified, the ‘latest’ tag is assumed. So for example for the Alpine image, FROM alpine:3.8
will run the version 3.8 image, and FROM alpine will use the latest tag, which could be equal to
another tag.
7
Using Payara Server with Docker
ENV
The ENV command sets an environment variable <key>=<value>. These environment variables will
then be available in all future layers. This command can use either of the following syntax:
RUN
The RUN command is used to run commands on the intermediary image. This is used in setup to run
commands that can be run before the container needs to start, for example creating directories or
running CURL to fetch an online resource.
The RUN command, along with some other commands such as ENTRYPOINT or CMD, accept two
forms of syntax since they are used to pass commands to the container. These forms are referred
to as exec form and shell form. The differences are covered below:
Shell Format
This format will invoke a shell to run the command. This means that the image must contain a shell
to run the command, and that if you do, environment variable substitution will be performed.
Exec Format
This format will run the executable directly. No variable substitution will be performed, which can
sometimes be useful in preventing strings being changed by the shell.
8
Using Payara Server with Docker
The RUN command can use either of these forms. When running in shell form, a backslash must be
used to continue the RUN instruction onto the next line. To reduce the number of layers produced
it’s recommended to run as many RUN commands as possible in the same layer, for example like so:
There is no functional reason to have a layer containing only one of these commands, so they are
merged to reduce layer complexity.
ADD
The ADD command is used to add a file from a local directory or remote URL to the fileystem of an
image, so that it can be used at runtime.
While the ADD command can specify a remote URL as a source, this is discouraged in favour of doing
so from a RUN command:
This is because the files not needed after extraction can be deleted as shown above.
Because of the automatic unpacking of the ADD command, the COPY command is recommended
when this is not required. The COPY command functions in the same way as ADD, but without
support for remote files or compressed file unpacking.
ENTRYPOINT
The ENTRYPOINT command specifies the executable to run on container start. It supports the same
exec and shell forms supported by the run command. When used in shell form (not recommended),
the ENTRYPOINT is run using /bin/sh -c. Because of this, signals will not be passed to the subprocess.
9
Using Payara Server with Docker
This means that your application will not respond to docker stop. There is no default ENTRYPOINT,
meaning that the CMD is used as the entrypoint unless one is specified.
CMD
The CMD command also specifies a command to run on container startup, but behaves depending
on how it’s specified. The CMD command has 3 forms. The first two are the same shell and exec
forms as ENTRYPOINT and RUN. The third form is when the exec form is while the ENTRYPOINT is
specified in exec form. In this use case, the CMD command will specify default parameters to the
ENTRYPOINT process. In all other cases, the CMD command sets the command to be executed on
container start.
Building a DockerFile
Once you’ve got a Dockerfile written, you must build the image to run it. Building the image will
incrementally build images by running the commands contained in the Dockerfile. You can build an
image using the following command:
To see the full syntax, see the official reference page8. An example usage would be building an image
called ‘test’ from the directory containing the Dockerfile using the following command:
The command will look for the default Dockerfile called ‘Dockerfile’ by default. You can then run the
container as with a remote image with docker run.
10
Using Payara Server with Docker
Payara provides Docker images for Payara Server which are tuned for production usage, but are also
useful in development. They are pre-configured in a way that makes it easy to start and use without
a custom Dockerfile. You can also build your own images using one of the Payara Server images as
a base to remove several required steps from your Dockerfile.
The Payara Server Web image is the same as the Full image but using Payara Server Web distribution.
Instructions will be the same for both.
A container created from the Payara Server Full Docker image will run the Payara Server production
domain as the main process. You can run the container with no configuration changes using the
following command:
11
Using Payara Server with Docker
This will simply run Payara Server inside the container, and map port 8080 to the host machine. You
can visit localhost:8080 and see the request forwarded to the container. To visit the admin console
on a localhost port you would also need to map port 4848. To see how to access Payara Server, see
the networking section in the Docker container introduction above.
When using the administration console or asadmin utility, the default username and password
are both ‘admin’.
When you run the Payara Server docker container with the default settings, Payara
Server will assume all host resources are available to it and it will allocate all the
available memory. To restrict how much memory and cpu can be used by the docker
container, use the options --cpus (nnumber of CPUs allowed to use) and -m (amount
of memory allowed to use), for example like this:
Deploying Applications
You can deploy via the admin console as with a non-containerized Payara Server instance (an instance
not running in a Docker container). If you don’t want to extend the Dockerfile with your own, the
Payara Server Full Docker image also provides a directory from which applications will be deployed
on startup. To utilise this, mount a directory using the following command:
The default entrypoint for the container will deploy all deployment files found in /opt/payara/deploy-
ments, so mounting a directory there that contains an application will deploy it on startup.
Alternatively, you can build your own Docker image from a Dockerfile to do the same:
FROM payara/server-full
COPY application.war $DEPLOY_DIR
Running the container produced from this image will also deploy the application on startup. The
image will need rebuilding when the application changes.
12
Using Payara Server with Docker
1. Search for a file with Payara Server commands stored in the file $POSTBOOT_COMMANDS (by
default /opt/payara/config/post-boot-commands.asadmin)
• if the file exists and contains commands, these commands will be executed when
Payara Server starts up
• you can copy a file with commands into this location when building a custom
docker image
2. Search for all deployable packages in the directory $DEPLOY_DIR and generate a script with
commands to deploy them when Payara Server boots
• DEPLOY_DIR is an environment variable which can be modified to search for deploya-
bles in a different directory
• all generated deploy commands are appended to the file $POSTBOOT_COMMANDS if
it exists
3. If shell scripts with suffix .sh found in $SCRIPT_DIR/init.d directory (by default /opt/
payara/scripts/init.d), they are executed
• you can copy your own scripts into that directory when building a custom docker image
or you can mount the directory to your local directory with scripts
4. Payara Server starts and executes the script $POSTBOOT_COMMANDS, which by default con-
tains commands to deploy found applications and any custom commands
• Payara Server process listens to all signals sent to the Docker container and correctly
shuts down when you stop the container with docker stop
So if you wanted applications to be deployed as usual but the container IP to be printed out initially,
you might create a bash script (test.sh) with the following contents:
#!/bin/bash
ip a
This would cause the container IP details to be printed out before starting the server.
13
Using Payara Server with Docker
Environment Variables
The following environment variables are available for use. When edited either in a Dockerfile or
before the startInForeground.sh script is ran, they will change the behaviour of the Payara
Server instance.
• JVM_ARGS - Specifies a list of JVM arguments which will be passed to Payara Server in the
startInForeground.sh script.
• DEPLOY_PROPS - Specifies a list of properties to be passed with the deploy com-
mands generated in the generate_deploy_commands.sh script, For example
‘--properties=implicitCdiEnabled=false’.
• POSTBOOT_COMMANDS - The name of the file containing post boot commands for the Payara
Server instance. This is the file written to in the generate_deploy_commands.sh script.
• PREBOOT_COMMANDS - The name of the file containing pre boot commands for the Payara
Server instance.
The following environment variables shouldn’t be changed, but may be helpful in your Dockerfile.
If you want to change the admin password instead of using the default one, it’s
not enough to change the password stored in the file $PASSWORD_FILE. You also
need to use the following command to change the master password before starting
Payara Server:
14
Using Payara Server with Docker
And you also need to supply the file /mypasswordfile with the current admin
password (in the AS_ADMIN_PASSWORD variable) and the new password (in the
AS_ADMIN_NEWPASSWORD variable). Then you need to change the password in the
file $PASSWORD_FILE so that Payara Server starts with the correct password.
You can add this command in your custom Docker image (using the RUN Dockerfile
command) or you can place it in a shell script in the init.d directory inside the
Docker container.
Running Commands
If you need to modify the configuration of Payara Server in your custom Docker images, you can do
it by adding asadmin commands into the following files:
For example, the following Dockerfile would instruct Payara Server to enable the HealthCheck Service
after the core server is booted:
Dockerfile
FROM payara/server-full
RUN echo 'healthcheck-configure --dynamic=true --enabled=true' > $POSTBOOT_
COMMANDS
15
Using Payara Server with Docker
Under usual circumstances, you shouldn’t modify the entrypoint or the CMD argument for a Payara
Docker container. Instead, specify additional shell scripts in the init.d directory or Payara Server
commands in the $POSTBOOT_COMMANDS file, or modify provided environment variables.
To cluster using this method, first find the IPs that will be used by your Docker containers. This is
explained in the earlier section ‘Basic Networking’. Knowing this, you must enable TCP/IP discovery
on the instances. This can be done either using your Dockerfile, or an init script dropped in /opt/
payara/scripts/init.d. Assuming that your Docker containers are assigned IPs of between 172.17.0.2
and up, the following Dockerfile will produce containers that cluster in the aforementioned fashion:
FROM payara/server-full:5.184
RUN echo 'set configs.config.server-config.hazelcast-config-specific-
configuration.enabled=false' > $PREBOOT_COMMANDS
RUN echo 'set-hazelcast-configuration --clusterMode tcpip --tcpipmembers
172.17.0.1-99:4900' > $POSTBOOT_COMMANDS
First, in order to avoid starting Hazelcast with the default configuration, Hazelcast is disabled by
executing the set command before server is booted. Then, after the server is booted, Hazelcast
data grid is enabled and configured to use the tcpip cluster mode.
16
Using Payara Server with Docker
Payara Server also support DNS and Kubernetes® discovery modes which will be more suitable for
docker-compose and Kubernetes environment respectively. More information on discovery modes
can be found here: https://docs.payara.fish/documentation/payara-server/hazelcast/discovery.html.
References
1. https://docs.docker.com/install/
2. https://docs.docker.com/install/linux/linux-postinstall/
3. https://docs.docker.com/engine/reference/commandline/docker/
4. https://docs.docker.com/engine/reference/commandline/run/
5. https://docs.docker.com/engine/reference/commandline/commit/
6. https://docs.docker.com/engine/reference/builder/
7. https://hub.docker.com/_/scratch
8. https://docs.docker.com/engine/reference/commandline/build/
9. https://hub.docker.com/r/payara/server-full/
10. https://hub.docker.com/r/payara/server-web/
Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other
countries. Docker, Inc. and other parties may also have trademark rights in other terms used herein.
Kubernetes is a registered trademark of The Linux Foundation in the United States and/or other countries.
Hazelcast is a registered trademark of Hazelcast, Inc.
Ubuntu is a registered trademark of Canonical in the United States and/or other countries.
Apache is a registered trademark of the Apache Software Foundation.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries.
Mac is a trademark of Apple Inc., registered in the U.S. and other countries.
[email protected] +44 207 754 0481 www.payara.fish
Payara Services Ltd 2019 All Rights Reserved. Registered in England and Wales; Registration Number 09998946
Registered Office: Malvern Hills Science Park, Geraldine Road, Malvern, United Kingdom, WR14 3SZ
17