--- updatedAt: 2026-03-31T13:33:41.000Z agentTools: projectIndex: https://esf.eurotech.com/llms.txt --- # ESF on Docker ESF is also distributed as a Docker container based on RHEL ubi8 and rockylinux. To run the container, detached, execute: ```shell # Replace with the proper image name # Replace with the desired version number # Replace with a unique 32 characters password docker run -d -p 443:443 -e ESF_MASTER_PASSWORD= -t : ``` > ❗️ 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: ```shell docker images ``` ### List Running Docker Containers To list all the available instances (both running and powered off) type: ```shell docker ps -a ``` ### Start/Stop a Docker Container ```shell docker stop docker start ``` 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: ```shell 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= -t : ``` > 🚧 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: ```shell docker run -d -p 443:443 --mac-address -e ESF_MASTER_PASSWORD= -t : # 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: ```shell docker logs ``` 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: ```shell --log-opt max-size=50m ``` ### VPN Support To run ESF's VPN client correctly, you must start the ESF Docker container with the **--privileged** option. For example, to run the container detached with the **--privileged** option, execute: ```shell # Replace with the proper image name # Replace with the desired version number # Replace with a unique 32 characters password docker run -d -p 443:443 -e ESF_MASTER_PASSWORD= --privileged -t : ``` ### Access to the container terminal To access to the shell inside the container, run the following command: ```shell docker exec -it /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](https://esf.eurotech.com/docs/directory-layout-1) and the [Move to Production](https://esf.eurotech.com/docs/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. ```dockerfile 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. ```shell 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. ```shell docker run -d -p 443:443 -e ESF_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).