The Docker image for the 64-bit Linux version of the AH Formatter V7.1 Command-line Interface is available for download from Docker Hub at https://hub.docker.com/r/antennahouse/ahfcmd71/.
The Docker image requires a license file for the 64-bit Linux version of AH Formatter V7.1 to be able to run. The AH Formatter V7.1 in the Docker container will not run when the license is not found.
The AH Formatter V7.0 Docker image is also available from Docker Hub.
The tags and the labels of the Docker image indicate the AH Formatter V7.1 version.
The Docker image is tagged with the major and point release numbers plus the maintenance and build numbers. Images containing maintenance releases of AH Formatter V7.1 are all tagged with the same major and point release numbers but differ in their maintenance and build numbers. Every image is also tagged as the ‘
latest’ version. Each new maintenance release replaces the current image on Docker Hub. The following table illustrates which tags will change over a series of releases:
|AH Formatter version||Docker tags|
||Major version||Major + Point||Major + Point + Maintenance||Build|
docker inspect” to obtain the version information for the AH Formatter V7.1 in the Docker image:
$ docker inspect --format='' antennahouse/ahfcmd71:7 AHFCmd : AH Formatter V7.1 R1 for Linux64 : 126.96.36.199063 (2021-01-27T19:49+09)
Log in to Docker before pulling the Docker image.
It is necessary only to pull the image using one of its tags. If the image is pulled as ‘
antennahouse/ahfcmd71:7’ or ‘
antennahouse/ahfcmd71:7.1’, then it possible for Docker to automatically pull a newer version, when that becomes available, to obtain new bug fixes and other improvements. However, because the image could change without notice, this is less stable than pulling the image tagged with its maintenance and build numbers.
docker pull” command and output:
$ docker pull antennahouse/ahfcmd71:7 7: Pulling from docker.io/antennahouse/ahfcmd71 be8881be8156: Pull complete 2129e1a8a660: Pull complete f5ab6673de2a: Pull complete 3d0714c9f87b: Pull complete Digest: sha256:8440e6988d6f166b06ddd1cee0bf8da9a0fc8ab3634a045f0bea2167e57a2e80 Status: Downloaded newer image for docker.io/antennahouse/ahfcmd71:7
The image IDs are shown as examples only. The IDs will be different for every release of the Docker image.
The Docker image requires an ‘
AHFormatter.lic’ license file to be able to run. The Docker container can mount just the license file, or it can mount an ‘
etc’ directory that can also include, for example, a custom ‘
font-config.xml’ that may refer to custom font files. The custom fonts can be included in or under the mounted ‘
etc’ directory or they could be in a separate directory that is mounted in a different location.
The examples below show only how to mount a license file. Other aspects of the Docker command line are covered in other sections.
Mount just an ‘
AHFormatter.lic’ file in the current directory read-only (with ‘
:ro’) as ‘
/AHFormatter/etc/AHFormatter.lic’ in the Docker container:
docker run -v `pwd`/AHFormatter.lic:/AHFormatter/etc/AHFormatter.lic:ro ...
docker run -v %cd%\AHFormatter.lic:/AHFormatter/etc/AHFormatter.lic:ro ...
docker run -v $PWD/AHFormatter.lic:/AHFormatter/etc/AHFormatter.lic:ro ...
Mount an entire ‘
etc’ subdirectory of the current directory, possibly with a custom ‘
font-config.xml’ and custom fonts that are in a subdirectory of the ‘
docker run -v `pwd`/etc:/AHFormatter/etc:ro ...
docker run -v %cd%\etc:/AHFormatter/etc:ro ...
docker run -v $PWD/etc:/AHFormatter/etc:ro ...
Other files in the ‘
etc’ directory are omitted from the graphic only for clarity. The mounted ‘
etc’ replaces the entire ‘
etc’ directory in the Docker container. The mounted ‘
etc’ must contain all of the files and subdirectories that the ‘
AHFCmd’ in the Docker container will use, including, for example, the ‘
hyphenation’ subdirectory that contains hyphenation dictionaries.
Additional font directories can be mounted at other locations in the Docker container by using additional ‘
-v’ parameters on the Docker command line. The ‘
font-config.xml’ in the mounted ‘
etc’ must refer to font files in their locations in the Docker container, not in their locations on the host computer.
All of the AH Formatter V7.1 command line parameters may be used. The parameters after the image name on the Docker command line – after ‘
antennahouse/ahfcmd71:7’ in the following examples – are used as command-line parameters for AH Formatter V7.1.
Command-line parameter arguments that refer to files must refer to locations on the file system of the Docker container, not to locations on the host computer. Access to external resources through network access – for example, to an image or a font file retrieved using HTTP – is dependent on the Docker container being configured with network access.
These examples omit providing an AH Formatter license file to the Docker container. See the preceding section for how to provide the license file.
When the input is a single file with no dependencies on any other local file – that is, the input does not refer to any external images, stylesheets, or other files on the file system – then the input can be piped into the container and the output piped to a file on the host computer.
docker run -i --rm antennahouse/ahfcmd71:7 -d @STDIN -o @STDOUT \ < hello-world.fo > hello-world.pdf
docker run -i --rm antennahouse/ahfcmd71:7 -d @STDIN -o @STDOUT ^ < hello-world.fo > hello-world.pdf
Redirecting the PDF output from Docker to a file on the host file system does not work in Power Shell. The redirected PDF data is corrupted because Power Shell filters the data to normalize both the encoding and ends of lines.
Access to other resources through network access – for example, to an image or a font file retrieved using HTTP – depends on the network access that is configured for the Docker container.
When the input has dependencies on external files on the host file system – for example, the input is an XSL-FO file that uses <fo:external-graphic> – then one or more directories can be mounted on the Docker container.
When the input and all of its local dependencies are under one directory and all file references are relative references, then the directory containing all of the files can be mounted on the container using the ‘
-v’ option. The reference to the input file on the “‘
docker run’” command line is to its location on the file system of the Docker container, not to its location on the host computer.
The directory containing the input files can be mounted read-only by adding ‘
:ro’ to the ‘
-v’ option value.
When the output is a single file, it can be piped to STDOUT.
docker run -i --rm -v `pwd`/in:/in:ro antennahouse/ahfcmd71:7 \ -d /in/hello-world.fo -o @STDOUT > hello-world.pdf
docker run -i --rm -v %cd%\in:/in:ro antennahouse/ahfcmd71:7 ^ -d /in/hello-world.fo -o @STDOUT > hello-world.pdf
When it is not convenient to direct the Docker output to a file – for example, when the output is multiple PDF volumes or multiple SVG files – the output can be written to a directory on the host computer that is mounted on the Docker container.
docker run --rm -v `pwd`/in:/in:ro -v /tmp:/out antennahouse/ahfcmd71:7 \ -d /in/hello-world.fo -o /out/hello-world.pdf
docker run --rm -v %cd%\in:/in:ro -v %cd%\out:/out antennahouse/ahfcmd71:7 ^ -d /in/hello-world.fo -o /out/hello-world.pdf
docker run --rm -v $PWD/in:/in:ro -v $PWD/out:/out antennahouse/ahfcmd71:7 ` -d /in/hello-world.fo -o /out/hello-world.pdf
Note that, for security reasons, the AH Formatter V7.1 in the Docker container executes as an ‘
ahf’ user with UID
9999 and GID
9999. If the permissions on the host computer do not allow a user with UID
9999 and GID
9999 to write to the output directory, the AH Formatter V7.1 in the Docker container will fail to write any output.
Docker requires elevated privileges to run. Ensure that you take adequate precautions to minimize the risks inherent in running a program with elevated privileges.
To reduce potential security issues from running as ‘
antennahouse/ahfcmd71 image runs AH Formatter V7.1 as a user with UID
9999. On Linux, it is necessary to ensure that a user with UID
9999 can write to any mounted output volume.