The concept of a Docker node and instance are introduced in Payara Server 5.192 as a tech preview. The aim of these is to provide better native integration of Payara Server with Docker.

How Do Docker Nodes and Instances Work?

Docker Nodes, and the instances upon them, were designed to mimic the behaviour of the pre-existing SSH, DCOM, or CONFIG node instances, though as the name suggests are targeted towards creating and using instances housed within Docker containers.

Each Docker node has details pointing it to a machine, just like an SSH node, but also contains information pertaining to a Docker image and how to connect to the Docker REST API endpoint of the remote machine. Payara Server then uses these details when creating an instance to instruct the Docker engine of the remote machine to create a container and start a Payara Server instance within it. This instance will then be available for management from the DAS and should behave in the same way as any other instance, allowing you to deploy applications to it, have it join a deployment group, and manage its configuration & state.

How Do I Use Them?

As previously mentioned, efforts were made to make these new nodes behave much as the existing node types do. This also extends to the admin commands, so much like how creating an SSH node is done using the create-node-ssh command, creating a Docker node is done using the create-node-docker command:

asadmin create-node-docker --nodehost localhost --useTls true --dockerPasswordFile /opt/passwordfile --dockerport 2376 -–dockerImage payara/server-node:5.192 Docky

This new command takes the same options as the create-node-config (namely nodehost, installdir, nodedir, and node-name), though if you’re using the base Docker image that we’ve created for this feature you only need to specify the nodehost and node-name options (shown in the example above). The new options are as follows:

• dockerPasswordFile - This is the path to the password file (on the remote machine) that the Docker instance will use for authentication against the DAS. As Docker instances are always remote instances (even if the container is on the same machine as the DAS), this means that secure admin must be enabled for these instances to properly communicate with the DAS. Since secure admin requires a password to be set, a password file is mounted into the Docker container from which the instance will read this password from.
• useTls - Whether to use HTTP or HTTPS to communicate with the Docker engine. When you expose the HTTP port of Docker, by default it is completely open and unsecured, allowing anyone with access to the published endpoint to start poking the Docker engine. This should only be enabled if you’ve set up TLS, see the documentation for how to do this.
• dockerPort - The port that the Docker engine is listening on. Following the Docker documentation for exposing an HTTP port, Payara Server defaults to using 2376.
• dockerImage - The Docker image to use. The base image we provide is called payara/server-node:5.192. You are able to specify your own image, though Payara Server makes a number of assumptions so any image you provide should be based upon our provided image.

You can also create the node from the admin console, simply choose a type of Docker from the dropdown and fill out the details:

Once you’ve created your node, creating, starting, and stopping instances on it is done just as you would any other instance – nothing special or different is required:

asadmin create-instance --node Docky Insty
asadmin start-instance Insty
asadmin stop-instance Insty
asadmin delete-instance Insty

Deploying applications is also done just as you would any other instance:

asadmin deploy --target Insty appy.war

Now, configuring the Docker container of an instance itself. This is done by specifying system properties in the instance config, allowing configuration to be shared across multiple instances and overridden as required. Since Payara Server is communicating with the REST API of Docker, which uses JSON, some transformation has to be done so that you’re not literally writing out JSON on the command line. The solution settled on was to try and mirror the dotted name format of system properties already used within Payara Server.

In short, all options start with “Docker”, and each “level” of the JSON structure is denoted with a “.”. As an example of adding some configuring the memory and CPU shares of the container:

asadmin create-system-properties --target default-config Docker.HostConfig.Memory=2048:Docker.HostConfig.CpuShares=3

More examples and further information is available in the documentation.

Further Reading & Suggestions

As was mentioned at the very beginning of this blog, this feature is still in tech preview, meaning that things are subject to change and that development of this feature is still ongoing. With this in mind, our plan for the next iteration of this feature is to have the Payara Server instances automatically register and unregister themselves with the DAS, allowing this feature to more easily be used in auto-scaling environments.

If you have any further suggestions, please let us know; it costs nothing but time to raise an issue on GitHub or otherwise contact us!

See the Payara Server Documentation for more detailed instructions and information: https://docs.payara.fish/documentation/payara-server/docker/

View additional Docker resources: