How to Configure Payara in Docker?

When I started with the Application Server Glassfish years ago I used to configure the Server always directly in the domain.xml file. This is the file containing the configuration and all your customizations when you configure your Glassfish form the Web Admin Interface. The same is true for Payara Server which is more widespread in projects today. (The main different from Glassfish to Payara is, that Payara offers support where Glassfish is the reference implementation for Jakarta EE).

I’ve never gotten rid of my habit of configuring the server directly in the domain .xml, although there is a command-line tool called ‘asadmin‘ for doing the configuration. When you run you projects in Docker you even can copy the domain.xml into a Payara Docker image as you will do with your application. But these days I learned that this is a clumsy and impractical way to do this. The problem with tweaking the domain.xml directly is that you can miss some important XML tags or new coniguration details. So using the asadmin tool is more stable also over differnt versions of Payara.

Docker and asadmin

To configure the Payara Sever directly in your Dockerfile can be done easily when you use so called Preboot and Postboot commands. This are asadmin commands which can be placed in separate files.

So simply create two files called post-boot-commands.asadmin and pre-boot-commands.asadmin and copy these files into your custom Payara Docker image using the COPY command in your Dockerfile:

FROM payara/server-full
# add configuration files
USER root

# Preconfigure Resources
COPY ./my-scripts/preboot-commands.asadmin $POSTBOOT_COMMANDS
COPY ./my-scripts/post-boot-commands.asadmin $POSTBOOT_COMMANDS
RUN chown payara $POSTBOOT_COMMANDS

## Copy additional deployments here
## e.g. Postgres Driver
COPY ./my-scripts/postgresql-42.2.5.jar /opt/payara/paasDomain/lib/
...
USER payara

The Preeboot and Postboot scripts can contain any asadmin command to configure your server. For example to configure a JDBC Database Pool for Postgres the command will look like this:

# Create the JDBC connection pool for Postgres:
create-jdbc-connection-pool --datasourceclassname=org.postgresql.ds.PGSimpleDataSource --restype=javax.sql.DataSource --property user=${ENV=POSTGRES_USER}:password=${ENV=POSTGRES_PASSWORD}:Url=${ENV=POSTGRES_CONNECTION} my-database

# Create the JDBC resource:
create-jdbc-resource --connectionpoolid my-database jdbc/my-database

Now build your Docker image and start you server:

$ docker build -t my-payara .
$ docker run -p 8080:8080 my-payara

The Payara server will automatically execute the PreBoot and PostBoot scripts during startup and creates the configuration. In case your command is wrong or misspelled you will see the error message in the log file directly in the log file.

That’s it. Now you have a stable configuration setup for a Payara Docker Image that you can easily adapt to the latest version of Payara by simply upgrading the payara version in your Dockerfile.

Payara Micro with Custom Configuration

This is a short guideline how to create a payara-micro Docker container with a custom configuration. A custom configuration is needed if you want to configure application server resources like database pools, mail resources or other stuff needed by your application.

1) Downlaod the payara-micro.jar

First you need to download the payara-mciro jar. Go the the official payara download page: https://www.payara.fish/software/downloads/

2) Copy the domain.xml

Next you can inspect the jar file and copy the domain.xml from the config directory

/MICRO-INF/doman/domain.xml

Now you can customize the domain.xml as needed by your project. The configuration is identically to payara-full so you can add all additional resources and configuration. For example you can add a custom data pool configuration into the resources section of the domain.xml.

3) Create a Dockerfile

Now you can create your custom Dockerfile. Payara-micro can be configured with launch options in several ways. One of them allows you to define a custom location of your configuration and domain.xml files. See the following example:

FROM payara/micro
USER root
# create a custom config folder
RUN mkdir ${PAYARA_HOME}/config
COPY domain.xml ${PAYARA_HOME}/config/
COPY postgresql-42.2.5.jar ${PAYARA_HOME}/config
RUN chown -R payara:payara ${PAYARA_HOME}/config
USER payara
WORKDIR ${PAYARA_HOME}
# Deploy artefacts
COPY my-app.war $DEPLOY_DIR
CMD ["--addLibs","/opt/payara/config/postgresql-42.2.5.jar", "--deploymentDir", "/opt/payara/deployments", "--rootDir", "/opt/payara/config","--domainConfig", "/opt/payara/config/domain.xml"]]

In this Dockerfile derived from the official payra/micro I create a new config/ folder to copy the jdbc-driver and the domain.xml.

The CMD option is important here. I added the following custom settings:

  • –addLibs – adds the postgresql jdbc driver
  • –deploymentDir – set the default deployment directory
  • –rootDir set the configuration directory to our new /opt/payara/config/ folder
  • –domainConfig – define the location of the custom domain.xml

With the CMD option –rootDir you can specify what directory Payara Micro should use as its new domain directory. Adding files to this directory will replicate the behavior of a Payara Server’s domain configuration. Payara-Micro automatically copies the folder with configuration files we do not specified explicitly. So at the end the folder contains all necessary configuation.

The CMD option –domainConfig is necessary. Otherwise payara-micro will ignore your custom domain.xml . More information which options can be added can be found here.

4) Build and Launch your Custom Docker Image

Finally you can now build your custom Docker image…

$ docker build --tag=my-custom-payara-micro .

…and start your docker container:

$ docker build --tag=my-custom-payara-micro .

Now you launched (hopefully without errors your custom payara-micro). I hope this helps you to get started with payara-micro and docker.

Payara Autodeploy with the Eclipse Manik Plugin

Manik-Hot-Deploy is a plugin for the Eclipse IDE which brings auto-deploy and hot-deploy functionallity to the development of web applications. The plugin is Open Source and supports Glassfish, Payara, JBoss, Wildfly and other application servers.

With the latest Release 1.0.6 the plugin improves the Payara Autodeploy support. The new version provides a setting for the target folder with a default setting for maven projects.

To enable the autodeploy feature for Payara you also have to set ‘autodeploy-enabled=true in the ‘das-config’ section of the domain.xml file.

<das-config dynamic-reload-enabled="true" autodeploy-enabled="true"></das-config>

Also hot-deployment is supported for Payara, Wildfly and other application servers. Find the full details on the Wikipage on Github.

Payara – Mail Resources

Running an application in Payara you can use a Mail Resource to send mails via SMTP.

In your Java EE code you can inject a Mail Resource by its name:

@Resource(lookup = "mail/my.mail.session")
....
Transport trans = mailSession.getTransport("smtp");
trans.connect();
.....

The Mail resource can be declared in the Payra Web Admin Console in the section “Resources ->JavaMail Sessions”.

Or you can define a mail resource directly in the domain.xml file:

....
 <resources>
  ...
  <mail-resource auth="false" host="smarthost" from="info@foo.com" user="admin" jndi-name="mail/my.mail.session"></mail-resource>
  </resources>
  <servers>
    <server config-ref="server-config" name="server">
      ....
      <resource-ref ref="mail/my.mail.session"></resource-ref>
    </server>
  </servers>
....

If you define the mail resource directyl in your domain.xml file take care about the ‘resource-ref’ declaration in the seciton ‘<servers>’. If you miss this, than your application will not find the mail resource to be injected!

Running Payara on Docker in Debug Mode

The Payara project provide a well maintained docker image on Docker Hub. Since version 5.192 you can easily create a docker image which runs Payara in Debug mode. You need just to add the environment variable “PAYARA_ARGS”

FROM payara/server-full:5.192
...
ENV PAYARA_ARGS --debug

COPY my-example.war $DEPLOY_DIR

Or you can also set the environment in your docker-compose.yml file:

version: "3.6"
services:
....  
  my-server:
    image: payara/server-full:5.192
    environment:
      PAYARA_ARGS: "--debug"
    ports:
      - "8080:8080"
      - "4848:4848"
      - "8181:8181"
      - "9009:9009"
....

After that Payara starts in Debug-Mode and listens to port 9009.