ChangelogDownloads
HomeGuidesChangelog
ChangelogDownloadsSupportMulti-service IoT Edge GatewaysEUROTECH
Guides
SupportMulti-service IoT Edge GatewaysEUROTECH
These docs are for v6.1.0. Click to read the latest docs for v7.5.0.

ESF on Docker

Suggest Edits

ESF is also distributed as a Docker container based on RHEL Atomic 7.4 and CentOS 7.

To run the container, detached, execute:

# Replace <image> with the proper image name
# Replace <version> with the desired version number
docker run -d -p 80:80 -t <image>:<version>

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 80:80 -e ENV_XMS_SIZE='2048m' -e ENV_XMX_SIZE='2048m' -e ENV_XSS_SIZE='256k' -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 80:80 --mac-address <MAC address> -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 across 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

ESF Container Persistence

ESF Docker images, when downloaded from the registry do not offer a persistence between containers, therefore if an instance crashes for some reason and it is no longer possible to bring it back up, you'll need to restart from scratch the container and re-configure it with the latest snapshot and configuration.

To prevent this from happening, two paths can be followed: it is possible to either build a new image starting from ESF's container image using a Dockerfile, or leverage Docker Volumes in order to import data necessary to ESF from some mountpoints on the host's file system.

🚧

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

ESF custom image creation via dockerfile

In order to create a Custom image of ESF, it is possible to create a work directory, then inside it copy the necessary files (such as the unencrypted snapshot, the packages and the relative dpa.properties file), then create a new file called Dockerfile.
These files can be either created ad-hoc, or for example downloaded from a running ESF container by means of a shared directory.

For example, in order to create a Custom ESF docker image which from scratch starts with the WireScriptFilter package pre-installed and a small Wire Graph, after I gathered the full snapshot file from ESF, as well as the /opt/eurotech/esf/data/dpa.properties and the /opt/eurotech/esf/data/packages/com.eurotech.wire.script.filter_1.0.300.dp files, the Dockerfile would result in something like:

FROM registry.everyware-cloud.com/eurotech/esf:6.1.0-centos

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

At this point, it is possible from the work directory to build a Custom ESF Container by issuing:

docker build -t custom_esf .

Docker will then build a new image with repository name "custom_esf" and "latest" as tag. If this container is then executed, it will start with the applied configuration on board.

🚧

When adding the snapshot to the Custom Image, any epoch timestamp in the past can be used; it is advisable to not overwrite "snapshot_0.xml"

ESF Persistence using Docker Volumes

Another way to implement file persistence with Docker is by means of the Docker Volumes (or if preferred Docker mountpoints): if some of the files necessary for ESF to start are gathered from the host File System, ESF can be persisted over different containers instances, edited and updated more easily from the host FS and even partly persisted across different ESF releases.
By having different ESF releases images, running exploiting Docker Volumes, it is possible to interchange ESF releases (when compatible) on-the-fly.

❗️

In order to use this feature it is mandatory to run ESF containers always specifying the same MAC address, or for security purposes the framework will refuse to start with an "Environment not safe" error!

In order to implement this, certain parts of ESF's File structure will need to be overwritten, and these are:
/opt/eurotech/esf/data
/opt/eurotech/esf/user/snapshots
/opt/eurotech/esf/user/security
/opt/eurotech/esf/framework

As a first thing, the docker volumes will need to be created:

docker volume create esf_data
docker volume create esf_snapshots
docker volume create esf_security
docker volume create esf_fw_6.1.0

It is advisable to create the "framework" volume (in the example fw) with the specific ESF release, since this directory is not interchangeable between ESF releases.

Once the containers are created, there will be the need to import on the host the keystores, and some policy and settings files.

The keystores cacerts.ks and certificates.ks can be downloaded at the following links: cacerts.ks
certificates.ks
These two keystores can both be accessed with password "changeit".

Keep in mind that the "kura.properties" file will need to be updated with the correct password for both keystores before ESF starts for the first time using the volumes.

In order to gather the rest of the files, a container can be instantiated on-the-fly and one of the volumes can be bound on e.g. /tmp (which will be used to move data from the container to the host).
After starting the container with the volume attached in detached mode, a shell can be spawned on the container with:

docker exec -t -i <docker container process> /bin/bash

Alternatively, the files can be gathered from the host FS by searching for them with a "find" or a "locate"; they will be in Docker's configurations directories, which by default is /var/lib/docker/.

The files needed are (path is relative to ESF's container FS, not host FS):

/opt/eurotech/esf/user/snapshots/snapshot_0.xml 
### (make sure it is in plain text and not encrypted!)
/opt/eurotech/esf/user/security/security.policy
/opt/eurotech/esf/framework/kura.properties
/opt/eurotech/esf/framework/config_debug.ini
### (or config.ini if ESF is in Production Mode)
/opt/eurotech/esf/framework/jdk.dio.policy
/opt/eurotech/esf/framework/jdk.dio.properties

After gathering the file, modifying the "kura.properties" by adding the keystores' password, the files can be copied in the respective volumes:

cp dpa.properties /var/lib/docker/volumes/esf_data/_data/
cp packages /var/lib/docker/volumes/esf_data/_data/

cp snapshot_0.xml /var/lib/docker/volumes/esf_snapshots/_data/
cp security.policy /var/lib/docker/volumes/esf_security/_data/

cp cacerts.ks /var/lib/docker/volumes/esf_security/_data/
cp certificates.ks /var/lib/docker/volumes/esf_security/_data/.certificates.ks

cp kura.properties /var/lib/docker/volumes/esf_fw_6.1.0/_data/
cp config_debug.ini /var/lib/docker/volumes/esf_fw_6.1.0/_data/
cp jdk.dio.policy /var/lib/docker/volumes/esf_fw_6.1.0/_data/
cp jdk.dio.properties /var/lib/docker/volumes/esf_fw_6.1.0/_data/

At this point, docker run can be invoked specifying the volumes, in the following way; remember that the MAC address will now become mandatory for persistence:

docker run -p 80:80 -d --mac-address 00:11:22:33:44:55 -v esf_data:/opt/eurotech/esf/data -v esf_snapshots:/opt/eurotech/esf/user/snapshots -v esf_security:/opt/eurotech/esf/user/security -v esf_fw_6.1.0:/opt/eurotech/esf/framework <container ID>

❗️

It is advisable to store the various configuration files during this initialization process, and copy them in the volumes instead of moving them: if for some reason the first startup of ESF fails, but some files get encrypted, you might need to wipe clean the volumes and copy the unenecrypted files back in again in order to retry.

If different versions of ESF are available as containers, and the releases are compatibles, if a new Docker Volume is created as explained above in order to store the "Framework" files specific for the release, the old container can be stopped and the new one started with all the bundles and configuration of the old one in place.

In order to find out if two releases are compatible, you can write to ESF' Customer Support Portal.

Updated almost 5 years ago