AH Formatter Docker Image

The 64-bit Linux version of the AH Formatter V6.6 Command-line Interface is available as a Docker image on Docker Hub: https://hub.docker.com/r/antennahouse/ahfcmd/

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

Tags

The AH Formatter V6.6 Docker image is tagged with multiple identifiers based on the AH Formatter V6.6 version. Maintenance releases of AH Formatter V6.6 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 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
V6.6 R1 latest 6 6.6 6.6.0 6.6.1.34539
V6.6 MR1 6.6.1 6.6.x.xxxxx

To pull the image as antennahouse/ahfcmd:6 or antennahouse/ahfcmd:6.6 is less stable than pulling the image tagged as its maintenance or build numbers, but it does make it possible for Docker to pull a newer version, when it is available, to obtain new bug fixes and other improvements.

Pulling the Docker image

Log in to Docker before pulling the Docker image.

Sample “docker pull” command and output:

$ docker pull antennahouse/ahfcmd:6
6: Pulling from antennahouse/ahfcmd
be8881be8156: Pull complete 
5ff882512eae: Pull complete 
9c3a3af72ffc: Pull complete 
a4db580eb6e4: Pull complete 
Digest: sha256:7ae695a11f0538b3f83513fe313ce9061664f7dda3428cc483d4c43d3370afda
Status: Downloaded newer image for antennahouse/ahfcmd:6

Use “docker inspect” to obtain the version information for a pulled AH Formatter V6.6 Docker image without running the image:

$ docker inspect --format='{{.ContainerConfig.Labels.about}}' antennahouse/ahfcmd:6
AHFCmd : AH Formatter V6.6 R1 for Linux64 : 6.6.1.34539 (2018/08/29 13:12JST)

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:

  • 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 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 ...

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.

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/ahfcmd:6 -d @STDIN -o @STDOUT \
      < hello-world.fo > hello-world.pdf
  • Command Prompt:
    docker run -i --rm antennahouse/ahfcmd:6 -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/ahfcmd:6 \
      -d /in/hello-world.fo -o @STDOUT > hello-world.pdf
  • Command Prompt:
    docker run -i --rm -v %cd%\in:/in:ro antennahouse/ahfcmd:6 ^
      -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:6 \
      -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/ahfcmd:6 ^
      -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/ahfcmd:6 `
      -d /in/hello-world.fo -o /out/hello-world.pdf

Note that, for security reasons, the AH Formatter V6.6 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 V6.6 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/ahfcmd image runs AH Formatter V6.6 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.