“Docker is the world’s leading software container platform. Developers use Docker to eliminate “works on my machine” problems when collaborating on code with co-workers. Operators use Docker to run and manage apps side-by-side in isolated containers to get better compute density. Enterprises use Docker to build agile software delivery pipelines to ship new features faster, more securely and with confidence for both Linux, Windows Server, and Linux-on-mainframe apps.”

Docker & ionCube Encoder/Loader

With an increasing number of questions related to how to either use our Encoder CI Edition or Loader software within a Docker container, we thought it would be a good idea to consolidate a number of solutions from our help desk to setting-up Docker containers for them. We will also update this article as and when further tips come to light.


Loader Installation

ionCube Loader 10 works straight out of the box against Docker 1.12.6+ on Centos 7 within the docker.io/wordpress image with no additional tuning or configuration to the Docker environment apart from our usual updating of the php.ini file that includes reference to the loader via the zend_extension line.

Using A Container Based On Alpine?

While we have resolved all known issues with using the Loader within an Alpine Linux container (tested and confirmed working ionCube Loader 10.3.6 and Alpine 3.9), the Encoder is still experiencing issues due to Alpine not using glibc.

Due to Alpine’s regular update cycle, we continue to investigate any bug reports that suddenly surface; should you encounter a problem either report it to us or switch to a container based on glibc such as a Debian one.


Encoder Licensing

The most common issue for our Encoder within a Docker environment is the enforcement of our product licensing which by nature of Docker containers are generally volatile entities. Because of this our Encoder CI Edition provides a more forgiving licensing solution as opposed to the standard edition, and as such, the CI Edition we strongly encourage the use of for any container based scenarios.

Using A Dockerfile?

We DON’T advise the use of the Dockerfile RUN instruction to activate the license at the building stage e.g. RUN /ioncube/ioncube_encoder.sh --activate

Instead perform the licensing process via shell script with the ENTRYPOINT instruction (or better still pass as the command line option when starting the container) making use of the advice below.

Getting: No license could be found corresponding to the revoke request

This error generally happens when the Encoder can’t find any license information for the installed Encoder. This may appear odd in that the Docker container does in fact initially contain these license files but for some reason they are not visible to the Encoder. All is not lost however if you make use of consistent container identification such as including both the host name (--hostname ) and MAC address (--mac-address) options for your container as simply acquiring a new license with the --activate option will give the Encoder something to pass to the licensing system to confirm it is the same machine. The license will apply and encoding can resume. You can check for this situation in your encoding shell script if the Encoder exits with code 16. If it does run the Encoder with the --activate option and then you can resubmit your original encoding process.

The source of the problem may or may not be related to this issue: https://stackoverflow.com/questions/41867734/docker-1-13-0-volume-mapping-file-corruption

Getting: An error occurred in communicating with the ionCube licensing server

This is known to happen with Debian/Ubuntu images and appears to be related to the lack of a base networking package. To resolve this and to successfully license the Encoder use this command within the container (or update your Dockerfile as appropriate): apt-get install netbase

Here is a short video demonstrating the issue and above solution:

Normal Licensing Solution

To use our Encoder as it would function normally outside of a container, the Encoder can be mounted as part of a data container volume within your encoding container(s). This option is suitable for a single Docker host, but if you are using Docker Swarm or any other solutions where the container can run on any arbitrary host where there’s varying hardware type, use the ‘Aggressive’ solution below.

Here is a sample walk-through for setting this up:

  1. First create a data volume with: docker volume create --name encoder
  2. Then start up a new container so it can be configured: docker run -it --hostname docker1 --volume encoder:/encoder --mac-address 00:60:18:fa:ba:de debian bash
  3. In another terminal session find out the name of the container and copy over the Encoder tarball: docker cp ioncube_encoder5_10.0.tar.gz <cont>:/encoder
  4. And for this sample walk-through our encoding script: docker cp encode.sh <cont>:/encoder
  5. And sample source for encoding: docker cp hello.php <cont>:/encoder
  6. The result is that we now have the Encoder installed into a persistent volume which is mounted under the directory /encoder within the container.
  7. It is now safe to exit out of the container and all is setup ready for use.
  8. Each time the container is run (using item 2) with repeatable and consistent settings, running the /encoder/encode.sh script will start the encoding process
  9. Of course as this is an example, the files are basic and aimed at making it clear what is trying to be achieved. You will need to change the script and/or methods for your environment.

Sample files mentioned above:


<?php echo "hello"; ?>



echo "* Input dir..."
ls -la /encoder

echo "* Output dir..."
ls -la /tmp

echo "* Encode process"

cd /encoder/ioncube_encoder5_10.0

./ioncube_encoder.sh /encoder/hello.php -o /tmp/out.php

if [ $? = 16 ] ; then
        echo "* Unlicensed. Get one..."
        ./ioncube_encoder.sh --activate
        echo "* Retry encode process"
        ./ioncube_encoder.sh /encoder/hello.php -o /tmp/out.php

echo "* Output result"
ls -la /tmp

Note that the above shell script makes a check for the state of the licensing as sometimes the Encoder may lose its licensing state. Please see further back for the specific situation.


Aggressive Licensing Solution

In some instances (where excessive licensing traffic/checking) can be tolerated, it is possible to license the Encoder before it is used and then release the license once the encoding process has completed – similar to the previous solution but with the added step of the --deactivate after the encoding process. This can be performed using the the Encoder command line settings as found in the user guide via any CI/scripting process.

Here are a couple of examples of this manually performed (to demonstrate method) for both Centos and Debian:


Encoder License Recovery

Normal containers are by nature volatile and should the situation arise where a licensed Encoder has not been released from within it’s container, recovery of the license will require support assistance and so incur delay.

If the correct exited container can be located committing it to an image and then creating a new container from that image with the original MAC address via the --mac-address option, will allow a safe manual revocation of the license.

Additionally, if you happen to be using GitLab, there is a feature that allows you to reattach to the failed container and so release the license for your Encoder. Take a look at https://gitlab.com/gitlab-org/gitlab-runner/issues/3605

ionCube Encoder CI Edition

The CI Edition Encoder is the best solution for use within a CI environment, having changes to our licensing that better suit a container based system. The CI Edition comes with 2 license slots where licenses automatically become available for reuse every 24 hours, allowing for re-allocation of a previously licensed container is broken or has been destroyed before deactivation. This behaviour is only available with the CI Edition; our standard license agreement does not permit use of licenses in this way.

Using Docker On MacOS?

We welcome any comments, tips or experiences you have on the Mac that we can share with our users.


If you have any other tips and advice for Docker usage please let us know!

ionCube Docker Support