Docker Instances

A Docker instance is the term used to refer to an instance created on a Docker node. These instances exist within their own Docker containers, with the lifecycle of these containers being tied to the instance it was created for.

Managing an Instance

Docker instances should be manageable in much the same way as any other instance. Deployment of applications, assignation to Deployment Groups, editing of config, should all be done just as if the instance was a standard SSH or CONFIG instance.

Creating an Instance

Creating a Docker instance is done in exactly the same way as when creating a normal one: with the create-instance command.

asadmin create-instance --node DockerNode1 dockerInstance1

When you invoke this command, a Docker container of the same name will be created. If a Docker container of the same name already exists, the create-instance command will fail, and Payara Server will attempt to unregister the instance from the DAS.

Please note that it is required that secure-admin be enabled for Docker instances to start (which is why a passwordfile is mandatory when creating a Docker node).

When autonaming is enabled, Payara Server will only attempt to resolve conflicts with instance names - it will not attempt to resolve conflicts in container name.

Starting an Instance

Starting a Docker instance should be done just as if it were an instance on an SSH node. When the start-instance command is invoked, the DAS will contact the Docker Rest API as configured in the node config, and start the Docker container and the instance within it.

asadmin start-instance DockerInstance1

Deleting an Instance

Much as with when creating a Docker instance, deleting a Docker instance is done in the same way as other instances: with the delete-instance command. This will unregister the instance from the DAS, and delete the Docker container.

asadmin delete-instance DockerInstance1

Configuring the Docker Container

Configuration of the Docker containers is done via system properties in an instances config (and so can be shared across multiple instances).

A complete list of the available configuration options can be found in the Docker Engine REST API here: https://docs.docker.com/engine/api/v1.39/#operation/ContainerCreate

The image name is not configurable - Payara Server expects the image name to match the value from the node config

The configuration within Payara Server of the settings denoted in the above link takes the form of dotted names. These names adhere to the following syntax:

Each property is prepended with "Docker"
Each child object is specified individually, with all of its parents prepended to it
Arrays must be surrounded with square braces
Array values are separated using the vertical bar symbol "|"
The colon character is used to denote the value of an object within an array
Objects within an array are separated using a comma

Properties that are denoted by arrays of objects containing further objects or arrays are not currently supported. The Env property is unique in that the colon character is used to denote the equals sign, as Payara Server does not currently support properties that contain an equals in their value.

See below for some examples:

Example	Original JSON	Payara System Properties
Arrays must be surrounded with square braces & array values separated using the vertical bar symbol "\|"	{ENV: [arg1=foo,arg2=bar]}	Docker.Env=[arg1:foo\|arg2:bar]
Each child object of a parent object is specified individually	{HostConfig: {Memory: 2048, CpuShares: 3}}	Docker.HostConfig.Memory=2048 Docker.HostConfig.CpuShares=3
The colon character is used to denote the value of an object within an array & objects within an array are separated using a comma	{HostConfig: {BlkioDeviceReadBps: [{Path: /opt/foo, Rate: 24},{Path: /opt/bar, Rate: 48}]}}	Docker.HostConfig.BlkioDeviceReadBps=[Path:/opt/foo,Rate:24\|Path:/opt/bar,Rate:48]

Example

Original JSON

Payara System Properties

Arrays must be surrounded with square braces & array values separated using the vertical bar symbol "|"

{ENV: [arg1=foo,arg2=bar]}

Docker.Env=[arg1:foo|arg2:bar]

Each child object of a parent object is specified individually

{HostConfig: {Memory: 2048, CpuShares: 3}}

Docker.HostConfig.Memory=2048 Docker.HostConfig.CpuShares=3

The colon character is used to denote the value of an object within an array & objects within an array are separated using a comma

{HostConfig: {BlkioDeviceReadBps: [{Path: /opt/foo, Rate: 24},{Path: /opt/bar, Rate: 48}]}}

Docker.HostConfig.BlkioDeviceReadBps=[Path:/opt/foo,Rate:24|Path:/opt/bar,Rate:48]

Payara Server assumes that the network mode in use is bridged - it expects to be able to talk to each instance using the port listed in its config.

Creating Instances from Docker

For Payara Server 5.193, the default Docker Image now supports creating instances from Docker itself, making use of the auto-naming feature to resolve any conflicts. This opens up the possibility for limited autoscaling to be achieved; instances are still tied to nodes however, and so any scaling must be done on the same machine. When instances are created this way, unless specified the container name will not match that of the instance.

As alluded to in the previous paragraph, a Docker Node must be registered to the DAS to create instances from Docker. The instances must also be housed on the machine that maps to this Docker Node.

See below for some examples:

Creating a container with a set instance name, resolving conflicts:

docker container create --network host --mount type=bind,source="/home/anon/passwordfile.txt",target="/opt/payara/passwords/passwordfile.txt",readonly -e PAYARA_DAS_HOST=payaraDas -e PAYARA_DAS_PORT=4848 -e PAYARA_NODE_NAME=docky1 -e PAYARA_INSTANCE_NAME=insty1 payara/server-node:5.193

>>>     Instance named insty1 created in a container named elastic_ganguly
>>>     Instance named insty1-BamboozledBarrcuda created in a container named wonderful_yonath

Creating containers without specifying an instance name:

docker container create --network host --mount type=bind,source="/home/anon/passwordfile.txt",target="/opt/payara/passwords/passwordfile.txt",readonly -e PAYARA_DAS_HOST=payaraDas -e PAYARA_DAS_PORT=4848 -e PAYARA_NODE_NAME=docky1 payara/server-node:5.193

>>>     Instance named Magnanimous-Monkfish  created in a container named sleepy_elgamel

Creating a container without specifying an instance name, using the Docker REST API:

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -i 'http://docky1:2376/containers/create' --data '{
  "Image": "payara/server-node:5.193",
  "HostConfig": {
    "Mounts": [
      {
        "Type": "bind",
        "Source": "/home/anon/passwordfile.txt",
        "Target": "/opt/payara/passwords/passwordfile.txt",
        "ReadOnly": true

    ],
    "NetworkMode": "host"
 ,
  "Env": [
    "PAYARA_DAS_HOST=payaraDas",
    "PAYARA_DAS_PORT=4848",
    "PAYARA_NODE_NAME=docky1"
  ]
}