ESF on Docker

ESF is also distributed as a Docker container based on RHEL ubi8 and rockylinux.

To run the container, detached, execute:

# Replace <image> with the proper image name
# Replace <version> with the desired version number
# Replace <master_password> with a unique 32 characters password
docker run -d -p 443:443 -e ESF_MASTER_PASSWORD=<master_password> -t <image>:<version>

❗️

The ESF_MASTER_PASSWORD is a 32 characters key that will be used for all the encryptions performed by the framework.
Do not use keys of different sizes, otherwise the container will fail to start!

🚧

Eurotech suggests the usage of separate keys for each installation in order to reduce security concerns.

The ESF_MASTER_PASSWORD must be defined at container instantiation.

Toolbox

List Docker Images

To list all the installed docker images type:

docker images

List Running Docker Containers

To list all the available instances (both running and powered off) type:

docker ps -a

Start/Stop a Docker Container

docker stop <container id>
docker start <container id>

where ID is the identification number of the instance.

🚧

The ESF container is stateful. To preserve its configurations, use the docker stop and start commands.

Manage Memory Size

The amount of memory assigned to the JVM that is running ESF can be adjusted with the following parameters that have to be passed when executing the Docker image:

docker run -d -p 443:443 -e ENV_XMS_SIZE='2048m' -e ENV_XMX_SIZE='2048m' -e ENV_XSS_SIZE='256k' -e ESF_MASTER_PASSWORD=<master_password> -t <image>:<version>

🚧

The memory assigned to ESF can be changed only when in development mode. In production mode, to change those values, a fingerprint reload is required.

Docker Container MAC Address

In order to prevent Stealing Link between different Docker installations, the developer should specify a different MAC address assigned to the ESF containers that connect to the same Cloud instance.

This can be achieved specifying the following property in the docker run command:

docker run -d -p 443:443 --mac-address <MAC address> -e ESF_MASTER_PASSWORD=<master_password> -t <image>:<version>
# parameter format: 12:34:56:78:9a:bc
# Be aware that Docker does not check if manually specified MAC addresses are unique.

🚧

In order to maintain a proper container functionality, the MAC address should not be changed between container restarts.

Logging

The ESF container log can be inspected using the following command:

docker logs <container id>

The user can specify a maximum size of the log size handled by the host, specifying the following parameter when invoking the ESF Docker container:

--log-opt max-size=50m

VPN Support

In order to have the VPN client running in ESF properly working, the --privileged option has to be specified during the ESF Docker image start.

Access to the container terminal

To access to the shell inside the container, run the following command:

docker exec -it <container id> /bin/bash

🚧

SSH access to the running container is not supported by ESF 7.

ESF Container Customisation

The ESF Docker images are self-contained and they contain all the information needed to fully start and run the framework.
For certain deployments a customisation of the base image is needed, for example to pre-load custom deployment packages in the final production image.

🚧

Before reading the next parts, it is strongly suggested to read both the Directory Layout and the Move to Production sections of the documentation, in order to fully understand this process

Usual customisable areas are the packages configuration and the snapshot_0 configuration.
As an example, the following Docker file shows how to customise the base ESF 7 docker image to create a new image with an additional deployment package and a custom snapshot_0 to be used during the first boot.

FROM registry.everyware-cloud.com/eurotech/esf:7.1.0-rhel

COPY dpa.properties /opt/eurotech/esf/packages
COPY com.eurotech.wire.script.filter_1.0.300.dp /opt/eurotech/esf/packages/
COPY snapshot_test.xml /opt/eurotech/user/snapshots/snapshot_0.xml

The custom image can then be generated running the following command from the working directory that contains the Dockerfile.

docker build -t custom_esf .

custom_esf will be the name of the new image based on the ESF 7 one.

Externalise the ESF Persistence

In other deployment scenarios, it may be required to keep the framework persistence separate from the actual container instance. In this way, in case of a container instance failure or image update it will be possible to update the container instance, while keeping stable the framework persistence.

In order to achieve this, the ESF persistence needs to be externalised in separate docker volumes, to keep them decoupled from the main container persistence.
When starting a new ESF image instance, the volumes will be attached to the container instance to use the external volumes instead of the container defaults.

docker run -d -p 443:443 -e ESF_MASTER_PASSWORD='<master_password>' -v /Users/user/esf_persistence/packages:/opt/eurotech/esf/packages -v /Users/user/esf_persistence/user:/opt/eurotech/esf/user -v /Users/user/esf_persistence/data:/opt/eurotech/esf/data -t esf:7.0.0-centos-x86_64

In the example above, the ESF Image (esf:7.0.0-centos-x86_64) is run attaching as volumes 3 folders of the host machine mapped as corresponding paths in the ESF container instance filesystem.
In this way, the ESF image is run using the persistence held by the host machine, simplifying the upgrade process in case of an ESF image upgrade.

🚧

In order to have the ESF framework fully functional with the usage of docker volumes, the base filesystem structure needs to be preserved with all the needed files (both visible and hidden files preserved).