AH Formatter Docker Image

The Docker image for the 64-bit Linux version of the AH Formatter V7.0 Command-line Interface is available for download from Docker Hub at: https://hub.docker.com/r/antennahouse/ahfcmd70

The Docker image requires a license file for the 64-bit Linux version of AH Formatter V7.0 to be able to run. The AH Formatter V7.0 in the Docker container will not run when the license is not found.

The AH Formatter V6.6 Docker image is also available from Docker Hub.

Version Information

The tags and the labels of the Docker image indicate the AH Formatter V7.0 version.

Tags

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.0 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
latest Major version Major + Point Major + Point + Maintenance Build
V7.0 R1 latest 7 7.0 7.0.0 7.0.1.43022
V7.0 MR1 7.0.1 7.0.x.xxxxx

Labels

Use “docker inspect” to obtain the version information for the AH Formatter V7.0 in the Docker image:

$ docker inspect --format='{{.ContainerConfig.Labels.about}}' antennahouse/ahfcmd70:7
AHFCmd : AH Formatter V7.0 R1 for Linux64 : 7.0.1.43022 (2020-02-19T19:20+09)

Pull the Docker Image

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/ahfcmd70:7’ or ‘antennahouse/ahfcmd70:7.0’, 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.

Sample “docker pull” command and output:

$ docker pull antennahouse/ahfcmd70:7
7: Pulling from docker.io/antennahouse/ahfcmd70
be8881be8156: Pull complete
a49a7c0a29db: Pull complete
eb4a7f7e6d1e: Pull complete
354393e0526c: Pull complete
Digest: sha256:ca12861d0c4a270c7f493cc1a0dba06900dc17350b6598df733e50baefc975e6
Status: Downloaded newer image for docker.io/antennahouse/ahfcmd70:7

The image IDs are shown as examples only. The IDs will be different for every release of the Docker image.

License

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 ‘AHFormatter.lic

Mount just an ‘AHFormatter.lic’ file in the current directory read-only (with ‘:ro’) as ‘/AHFormatter/etc/AHFormatter.lic’ in the Docker container:

  • Bash:

    docker run -v `pwd`/AHFormatter.lic:/AHFormatter/etc/AHFormatter.lic:ro ...
  • Command Prompt:

    docker run -v %cd%\AHFormatter.lic:/AHFormatter/etc/AHFormatter.lic:ro ...
  • Power Shell:

    docker run -v $PWD/AHFormatter.lic:/AHFormatter/etc/AHFormatter.lic:ro ...

mount-ahformatter-lic

Mount ‘etc’ directory

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 ‘etc’ directory:

  • Bash:

    docker run -v `pwd`/etc:/AHFormatter/etc:ro ...
  • Command Prompt:

    docker run -v %cd%\etc:/AHFormatter/etc:ro ...
  • Power Shell:

    docker run -v $PWD/etc:/AHFormatter/etc:ro ...

mount-etc

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.

AH Formatter command-line parameters

All of the AH Formatter V7.0 command line parameters may be used. The parameters after the image name on the Docker command line – after ‘antennahouse/ahfcmd70:7’ in the following examples – are used as command-line parameters for AH Formatter V7.0.

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.

Examples

These examples omit providing an AH Formatter license file to the Docker container. See the preceding section for how to provide the license file.

Input with no local dependencies

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.

  • Bash:

    docker run -i --rm antennahouse/ahfcmd70:7 -d @STDIN -o @STDOUT \
      < hello-world.fo > hello-world.pdf
  • Command Prompt:

    docker run -i --rm antennahouse/ahfcmd70:7 -d @STDIN -o @STDOUT ^
      < hello-world.fo > hello-world.pdf
  • Power Shell:

    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.

Input with local dependencies

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.

Read-only directory to STDOUT

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.

  • Bash:

    docker run -i --rm -v `pwd`/in:/in:ro antennahouse/ahfcmd70:7 \
      -d /in/hello-world.fo -o @STDOUT > hello-world.pdf
  • Command Prompt:

    docker run -i --rm -v %cd%\in:/in:ro antennahouse/ahfcmd70:7 ^
      -d /in/hello-world.fo -o @STDOUT > hello-world.pdf

Output to host computer directory

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.

  • Bash:

    docker run --rm -v `pwd`/in:/in:ro -v /tmp:/out antennahouse/ahfcmd:7 \
      -d /in/hello-world.fo -o /out/hello-world.pdf
  • Command Prompt:

    docker run --rm -v %cd%\in:/in:ro -v %cd%\out:/out antennahouse/ahfcmd70:7 ^
      -d /in/hello-world.fo -o /out/hello-world.pdf
  • Power Shell:

    docker run --rm -v $PWD/in:/in:ro -v $PWD/out:/out antennahouse/ahfcmd70:7 `
      -d /in/hello-world.fo -o /out/hello-world.pdf

Note that, for security reasons, the AH Formatter V7.0 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.0 in the Docker container will fail to write any output.

Security

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 ‘root’, the antennahouse/ahfcmd70 image runs AH Formatter V7.0 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.