Working with External Configuration Files in Payara Micro

It is relatively common for applications to need additional configuration files outside of what is provided in Payara Server or Payara Micro. If you are used to using a custom security realm in Payara Server, for example, it may not be immediately clear how you can use the same file with applications deployed to Payara Micro.

Enter the rootDir

Payara Micro has a --rootDir command line option which allows you to specify what directory Payara Micro should use as its domain directory. Adding files to this directory will replicate the behavior of a Payara Server’s domain configuration. Much of the content of this directory will be familiar since it is effectively a much slimmer domain directory and the folders here function in the same way as with a Payara Server domain.

For example, if I start Payara Micro with the following command:

java -jar payara-micro.jar --rootDir /tmp/PM-rootDir

I will find that the PM-rootDir directory gets created if it does not exist. If it does exist, then it will not be recreated. This means that any additional files that you add to this directory (or subdirectories) will be unaffected by stopping and starting Payara Micro; in other words, your new root directory can be totally permanent!

Working With Uber JARs

Keep in mind that when you package Payara Micro with the --outputUberJar option in an Uber JAR, the additional options you specify on the command line will be “packaged” into the resulting output:

java -jar payara-micro.jar --rootDir /tmp/PM-rootDir --deploy myApp.war --outputUberJar myUberApp.jar

However, although this will maintain the --rootDir option, it will not package additional files added to the directory or its sub-directories, though your deployed applications will get packaged.

It is pretty straightforward to workaround this issue with deployment or CI scripts. However, this may seem a little unintuitive. The fact that these files are ignored is not unexpected: Payara Server exhibits the same behavior when adding files to the config directories of remote instances. A sync of the instance will result in improperly managed files being removed from its directories.

Still, it would be more convenient to be able to create the Uber JAR once and have all dependent artifacts and resources packaged within it; with that in mind, there is currently an open issue (PAYARA-1068) to add this new feature to Payara Micro! Keep your eye on the blog for more updates!

Below is the default contents of the root directory of Payara Micro:

➜  /tmp/PM-rootDir > tree -L 2
.
├── autodeploy
├── config
│   ├── admin-keyfile
│   ├── branding
│   ├── cacerts.jks
│   ├── default-web.xml
│   ├── domain.xml
│   ├── keyfile
│   ├── keystore.jks
│   ├── local-password
│   ├── lockfile
│   ├── logging.properties
│   ├── login.conf
│   ├── pid
│   ├── pid.prev
│   └── server.policy
├── docroot
├── lib
│   └── install
└── META-INF
    └── MANIFEST.MF
 
16 directories, 23 files

Docker is probably the best tool to use to make this portable right away, specifically Docker Compose. I was able to very quickly prepare a proof-of-concept with just a few steps, shown below:

1. Create a new docker-compose.yml file with the following contents:

version: '2'
 
services:
    payara-micro:
        image: payara/micro
        volumes:
            - ./microRootDir:/opt/payara/rootDir
            - ./deployments:/opt/payara/deployments
        entrypoint:
            - java
            - -jar
            - /opt/payara/payara-micro.jar
            - --deploymentDir
            - /opt/payara/deployments
            - --rootDir
            - /opt/payara/rootDir

 In the file above, I have defined two local directories; one to hold my deployment and another to hold the root directory and any configuration I want. These are mounted as volumes so that I can modify their contents from outside the containers.

2. Next, create the directories and the file I want to be included in the config:

I have created another directory called “config” below my “microRootConfig” directory, since that is where all the Payara Micro configuration will be held

3. Now, add the external config file to the ./microRootDir/config directory. Here, I have created a new file:

4. I can now bring up my container in the background using docker-compose up -d:

Running the tree command once again, I can see the --rootDir command has populated the rest of the microRootDir and config directory with the normal Payara Micro configuration.

The extra step of adding your external configuration at the end will soon be a thing of the past but, until then, Docker can be used to simplify deployment.