Payara Micro Docker Image Overview
Overview of the usage and details of the official Payara Micro Community Docker image.
Launch a new Payara Micro instance running in a container listening in port
8080 with the following command:
docker run -p 8080:8080 payara/micro
Keep in mind the following:
The instance will start with no deployed applications.
Accessing the default HTTP endpoint will yield a
404 - Not Foundresponse.
The instance’s JVM process runs under the
docker run -p 8080:8080 payara/micro:6.2023.5
Specifying the JDK Version
There are 2 different, alternative versions of the JDK images:
The default version which is based on JDK11, uses no suffix.
The JDK 17 version, which uses the
To switch from the default JDK 11 based image to the JDK 17 compatible one, just add the corresponding suffix to the tag’s name like this:
docker run -p 8080:8080 payara/micro:6.2023.5-jdk17
The default ports that are exposed by this image are:
8080 - HTTP listener
6900 - Datagrid’s Hazelcast port
The Payara Micro JAR file is located in the
/opt/payara/ directory (identified by the
HOME_DIR environment variable), which also is the default work directory of the image.
|The directory name is deliberately free of any versioning so that any scripts written to work with one version can be seamlessly migrated to the latest docker image.|
Payara Micro will deploy applications at startup time, depending on how you prefer to instruct the instance to execute the deployments. However, you have to make sure that the container has access to your application artefacts.
You can instruct the container to deploy applications using the following mechanisms:
Mount a deployment directory (local or in the network) as a Docker volume
Prepare a custom Docker image that includes your application artefacts.
Deploy your applications from a remote Maven repository.
Deploy Applications from a Directory
You can instruct the container to deploy all application artefacts that belong to a directory that is mounted as Docker volume mapped to the
/opt/payara/deployments (which is defined as the value of the
$DEPLOY_DIR environment variable) local directory.
The following command will start a new Payara Micro instance container and deploy all artefacts located in the
docker run -p 8080:8080 -v ~/payara-micro/applications:/opt/payara/deployments payara/micro
To only deploy a specific artefact within the directory, simply pass the
--deploy argument to the container’s run command and specify which application to deploy:
docker run -p 8080:8080 -v ~/payara-micro/applications:/opt/payara/deployments payara/micro --deploy /opt/payara/deployments/myapplication.war
|Make sure to prefix the artefact names with the absolute path to the local deployment directory.|
Deploy Applications using a Custom Image
You can also prepare a custom image based on the official Payara Micro Docker image and copy all application artefacts to the
$DEPLOY_DIR directory. This way, you can re-package your applications in a simple distributable unit.
The following sample Dockerfile can be used to prepare a custom Payara Micro image that deploys the
myapplication.war artefact at runtime:
FROM payara/micro COPY myapplication.war $DEPLOY_DIR
Deploy Applications from a Maven Repository
If your application’s artefact is already available in a Maven repository, you can instruct the container to download and deploy it directly. To do this, you’ll have to pass the
--deployFromGAV argument with the GAV coordinates of your artefact to the run command used to launch the container.
Here’s an example of how to deploy a sample application located in a local Maven repository:
docker run -p 8080:8080 payara/micro --deployFromGAV "fish.payara.examples:my-application:1.0-SNAPSHOT" --additionalRepository https://172.17.0.10/content/repositories/snapshots
Notice that the example also uses the
--additionalRepository argument to specify the URL of the repository where the artefact lives since by default, Payara Micro will only look for artefacts in the Maven Central repository.
Context Root Configuration
By default, the context root of each deployed application corresponds to the artefact’s file name. You can override this setting by using the
--contextroot startup argument.
To deploy an application using the default context root (
Here are some basic examples:
docker run -p 8080:8080 -v ~/payara-micro/applications:/opt/payara/deployments payara/micro --deploymentDir /opt/payara/deployments --contextroot myRoot
docker run -p 8080:8080 -v ~/payara-micro/applications:/opt/payara/deployments payara/micro --deploy /opt/payara/deployments/myapplication.war --contextroot ROOT
You can also prepare a custom Docker image that overrides the default
CMD instruction to specify the context root like this:
FROM payara/micro COPY myapplication.war $DEPLOY_DIR CMD ["--deploymentDir", "/opt/payara/deployments", "--contextroot", "my"]
Disable the Data Grid
Payara Micro will start in "clustering" mode by booting up the Data Grid, allowing other instances reachable in the network to join the grid automatically.
The Data Grid initialization and maintenance consumes extra resources, so in cases where clustering is not needed, it is recommended to disable the Data Grid completely.
To disable the Data Grid, you can pass the
--noHazelcast argument to the entry point of the run command:
docker run -p 8080:8080 -v ~/payara-micro/applications:/opt/payara/deployments payara/micro --noHazelcast
By default, Payara Micro will start with hazelcast enabled, allowing other instances reachable in the network to join the datagrid automatically and cluster.
Disabling hazelcast with the --noHazelcast option will also disable all features that depend on Hazelcast, including JCache. The
--noCluster option allows you to keep Hazelcast and therefore all features depending on Hazelcast, but disable clustering. This will significantly improve performance and is the recommended option if you require Hazelcast dependant features, but do not intend to use clustering.
To disable clustering, you can pass the
--noCluster argument to the entry point of the run command:
docker run -p 8080:8080 -v ~/payara-micro/applications:/opt/payara/deployments payara/micro --noCluster
Using Environment Variables
The following environment variables can be used to configure multiple settings of the Payara Micro instance. They can be either specified in a custom image’s
Dockerfile or passed to the
docker run command via the
Value for the JVM argument
Value for the JVM argument
Additional JVM arguments which will be used to configure the Payara Servers DAS JVM settings
The following is a list of variables used by the Docker image to set up the Payara Micro instance startup, so it is not recommended to alter their values:
The directory containing the Payara Micro JAR binary and the scripts used to run the instance.