Docker Nodes

A Docker node is similar to the existing SSH, DCOM, and CONFIG nodes in that it is a virtual representation of a Payara Server installation, providing connection details that the Domain Administration Server (DAS) uses to communicate with the installation to create, stop, start, and delete instances. Where it differs from these existing node types is that instances created against it are actually housed in Docker containers, and so also contains details on how to communicate with the Docker engine of the remote machine.

The Docker engine must expose its REST admin service on an HTTP port

Exposing the Docker REST Admin Service

To expose the REST admin service of the Docker engine, you need to specify the -H option in your DOCKER_OPTS environment variable, or otherwise specify it in the command that starts the docker service.

For example:

DOCKER_OPTS="-H=0.0.0.0:2376"

You can test that it is exposed by navigating to it with your browser (assuming you’re exposing the port in the example above): http://localhost:2376/info

Creating a Docker Node

Creating a Docker node is done in a similar manner to creating an SSH or CONFIG node, either by asadmin command, or by the Nodes page of the admin console.

Docker nodes do have some unique configuration properties however:

  • Docker Password File - This is the fully-qualified path of the password file that the Docker instance will use for authentication against the DAS. Please note, that this path should be the path to the file on the remote machine. This file should be a standard Payara password file as you would use with asadmin. This must be specified, as Docker instances require secure admin to be enabled to start.

  • TLS - Whether or not to use HTTPS to communicate with the Docker engine or not.

  • Docker Port - The port that the Docker engine is listening on. Defaults to 2376.

  • Docker Image - The Docker image to use. Payara Server will default to using the payara/payaraserver-node:5.26.0 image.

The configuration options of CONFIG nodes are also available, namely nodehost, nodedir, and installdir. Specifying the nodehost option remains mandatory, but for docker nodes the installdir and nodedir options can safely be left as their defaults unless you’re specifying your own Docker image.

Please take particular note of the Docker Password File option: this is mandatory and must be present on the remote machine. Payara Server Enterprise does not currently support propagating password files from the DAS to your remote machines. Secure admin must also be enabled for Docker Nodes to function correctly, which entails setting an admin password. See below for an example of enabling secure admin for the default admin user:

>asadmin change-admin-password --user admin
Enter the admin password>
Enter the new admin password>
Enter the new admin password again>
Command change-admin-password executed successfully.

>asadmin enable-secure-admin
Authentication failed with password from login store
Enter admin password for user "admin">
You must restart all running servers for the change in secure admin to take effect.
Command enable-secure-admin executed successfully.

>asadmin restart-domain

As an example of an extremely simple password file, here is the contents of a sample, passwordfile.txt:

AS_ADMIN_PASSWORD=changeit

Where "changeit" is the password of the default admin user.

Once you have ensured that you have secure admin enabled, and that a passwordfile granting access to the DAS is present on the remote machine, you can run the asadmin command for creating a Docker node:

asadmin create-node-docker --nodehost localhost --dockerPasswordFile /opt/passwordfile.txt --dockerport 2376 DockerInstance1
The admin console page for creating Docker nodes is the same as creating the other node types: simply select DOCKER as the node type from the dropdown.

Configuring TLS

As Docker must expose an HTTP port, it is recommended that it be protected using TLS outside of development environments.

A full guide for how to do so can be found here: https://docs.docker.com/engine/security/https/ In short, create self-signed TLS certificates (or use your own signed ones), and add them to your DOCKER_OPTS to secure the Docker REST admin service:

DOCKER_OPTS="--tlsverify --tlscacert=/home/anon/tls/ca.pem --tlscert=/home/anon/tls/server-cert.pem --tlskey=/home/anon/tls/server-key.pem -H=0.0.0.0:2376"

Assuming you followed this guide, you will need to perform the following steps to allow Payara Server to communicate with the Docker engine:

  1. Import the CA certificate into the Domain truststore (defaults to ${payaraHome}/glassfish/domains/${domainName}/config/cacerts.jks)

  2. Create a PKCS12 bundle from the client certificate and key

  3. Import the generated PKCS12 bundle into the Domain’s keystore (defaults to ${payaraHome}/glassfish/domains/${domainName}/config/keystore.jks)

Once you’ve enabled TLS for the Docker REST admin service and added the necessary certificates & keys to Payara Server, you can create a Docker Node with TLS enabled like so:

asadmin create-node-docker --nodehost localhost --useTls true --dockerPasswordFile /opt/passwordfile.txt --dockerport 2376 DockerInstance1
Please ensure that the useTLS option of the node matches whether or not you have configured TLS for the Docker engine, as otherwise any communication with the Docker engine will fail.