Web Interface for Formatter Docker Image

The Docker image for the combination of Web Interface V6.0 for AH Formatter Server & 64-bit Linux AH Formatter V6.6 is available for download from Docker Hub at https://hub.docker.com/r/antennahouse/xdsserver/.

To be able to run, the Docker image requires licenses for both the Web Interface V6.0 for AH Formatter Server and the 64-bit Linux AH Formatter V6.6. The Web Interface V6.0 for AH Formatter Server in the Docker container will not run unless both licenses are found.

Version Information

The tags of the Docker image indicate the version of the 64-bit Linux AH Formatter V6.6 that is bundled with Web Interface V6.0 for AH Formatter Server. (The ‘ahfcmd’ Docker image for the AH Formatter V6.6 command-line interface uses the same tag formats.)

The labels of the Docker image include version information for both the Web Interface V6.0 for AH Formatter Server and the 64-bit Linux AH Formatter V6.6.

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 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 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
V6.6 R1 latest 6 6.6 6.6.0 6.6.1.34539
V6.6 MR1 6.6.1 6.6.x.xxxxx

Labels

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

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

or for the Web Interface V6.0 for AH Formatter Server:

$ docker inspect --format='{{.ContainerConfig.Labels.xdsserverabout}}' antennahouse/xdsserver:6
xds version: 6.0MR3 (241) 2018-09-19 14:50 JST

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/xdsserver:6’ or ‘antennahouse/xdsserver:6.6’, 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/xdsserver:6
6: Pulling from antennahouse/xdsserver
be8881be8156: Pull complete 
87afd40ffc1e: Pull complete 
46c26bf1484f: Pull complete 
6f4da1ccc624: Pull complete 
d80f886906c8: Pull complete 
6bd436e56012: Pull complete 
4ff22c0923eb: Pull complete 
9a7abeb8c8d1: Pull complete 
38e75963a8b4: Pull complete 
fd5b36535f02: Pull complete 
c68a4086e992: Pull complete 
79f139412120: Pull complete 
d9fa9a25ffbf: Pull complete 
c6cfe28e6a09: Pull complete 
Digest: sha256:1f1785dc30cc6ac2b80a7d6b9b235d590fc4aedabe047eb68bc65f5cd2e7b388
Status: Downloaded newer image for antennahouse/xdsserver:6

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

License

To be able to run, the Docker image requires both an ‘xds.lic’ file for Web Interface V6.0 for AH Formatter Server and an ‘AHFormatter.lic’ file for AH Formatter V6.6. Antenna House provides both licenses in a Zip archive. The complete directories and files extracted from the Zip archive can be mounted directly on the Docker container.

The contents of the Zip file is:

The portion of the Docker command line to mount the extracted license files read-only (with ‘:ro’) on /license in the container is:

  • Bash:
    docker run -v `pwd`/license:/license:ro ...
  • Command Prompt:
    docker run -v %cd%\license:/license:ro ...
  • Power Shell:
    docker run -v $PWD/license:/license:ro ...

The Web Interface V6.0 for AH Formatter Server and the AH Formatter V6.6 in the container use the license files in /license:

Option File for Web Interface V6.0 for AH Formatter Server

The Docker image includes a default Option File for the Web Interface V6.0 for AH Formatter Server at /xds/server/xds-options.xml. This Option File does not specify any values:

<commandLine>
</commandLine>

The default Option File is meant to be overridden (if required) by an Option File that is mounted from the host machine to specify additional command line parameters to the Web Interface V6.0 for AH Formatter Server.

Maximum Number of Client Connections and AH Formatter Processes

The -mc option of Web Interface V6.0 for AH Formatter Server defaults to no limit on the maximum number of client connections. The -mp option defaults to no limit on the maximum number of AH Formatter V6.6 processes that can run at once. If the Docker container is run as part of a Docker Swarm or in a container-orchestration system such as Kubernetes, then it may be advisable to limit one or both of the number of client connections and the number of AH Formatter V6.6 processes and instead rely on the external controller to manage replication and scaling of containers in response to demand.

Examples

The Docker container for the Web Interface V6.0 for AH Formatter Server is typically run as a detached service. The container is started by running a Docker command. The Web Interface V6.0 for AH Formatter Server listens on port 9999 of its container, but Docker can bind that port to any port on the host machine when starting the container. Any user can access the Web Interface V6.0 for AH Formatter Server by using the Web Interface client or the Folder Monitoring Service on the same machine or on a different machine. The container is stopped by running another Docker command.

The Web Interface V6.0 for AH Formatter Server can either only accept unsecured connections or only accept connections that are secured using SSL. If the Web Interface V6.0 for AH Formatter Server is configured to use SSL, then the Web Interface V6.0 for AH Formatter Client or the Folder Monitoring Service must use SSL. See the SSL section of the Web Interface V6.0 for AH Formatter Online Manual for full details.

These examples omit providing license files to the Docker container. See the preceding section for how to provide the license files.

Web Interface for AH Formatter Server

Web Interface for AH Formatter Server is configured when it is started to accept either unencrypted connections or connections that are secured using SSL. The SSL parameters can be configured either on the Docker command line or through an Option File.

Start the Docker container

$ docker run -d --rm -p 9999:9999 --name=xdsserver antennahouse/xdsserver:6

Parameter Description
-d Run container in background and print container ID
-rm Automatically remove the container when it exits
-p 9999:9999 Bind port 9999 on the host (left-hand side) to port 9999 on the container (right-hand side)
-name xdsserver Assign xdsserver as the name of the container that is created from the image
antennahouse/xdsserver:6 Web Interface V6.0 for AH Formatter Server Docker image

SSL parameters on command line

Note that, depending on the operating system, the command line, including the keystore password, may be visible to other processes running on the same machine.

  • Bash:
    $ docker run -d --rm -v `pwd`/keystore.jks:/xds/server/keystore.jks:ro \
         antennahouse/xdsserver:6 \
         -java-prop javax.net.ssl.keyStore keystore.jks \
         -java-prop javax.net.ssl.keyStorePassword 123456 -ssl \
         -p 9999:9999 --name=xdsserver antennahouse/xdsserver:6
  • Command Prompt:
    > java docker run -d --rm -v %cd%\keystore.jks:/xds/server/keystore.jks:ro ^
         antennahouse/xdsserver:6 ^
         -java-prop javax.net.ssl.keyStore keystore.jks ^
         -java-prop javax.net.ssl.keyStorePassword 123456 -ssl ^
         -p 9999:9999 --name=xdsserver antennahouse/xdsserver:6
  • Power Shell:
    > docker run -d --rm -v $PWD/keystore.jks:/xds/server/keystore.jks:ro `
         antennahouse/xdsserver:6 `
         -java-prop javax.net.ssl.keyStore keystore.jks `
         -java-prop javax.net.ssl.keyStorePassword 123456 -ssl `
         -p 9999:9999 --name=xdsserver antennahouse/xdsserver:6
Parameter Description
-v `pwd`/keystore.jks:/xds/server/keystore.jks:ro Mount the keystore read-only (with ‘:ro’) as /xds/server/keystore.jks in the Docker container
-java-prop javax.net.ssl.keyStore keystore.jks Refer to the keystore by its location in the Docker container
-java-prop javax.net.ssl.keyStorePassword 123456 Provide the password for the keystore
-ssl Enable the use of SSL

SSL parameters as Option File values

When the keystore password is stored in an Option File, the password will not be visible to other processes running on the host machine. However, any process with the correct permissions will be able to read the Option File.

  • Bash:
    $ docker run -d --rm -v `pwd`/keystore.jks:/xds/server/keystore.jks:ro \
         -v `pwd`/xds-ssl-options.xml:/xds/server/xds-options.xml:ro \
         --name=xdsserver antennahouse/xdsserver:6
  • Command Prompt:
    > docker run -d --rm -v %cd%\keystore.jks:/xds/server/keystore.jks:ro ^
         -v %cd%\xds-ssl-options.xml:/xds/server/xds-options.xml:ro ^
         --name=xdsserver antennahouse/xdsserver:6
  • Power Shell:
    > docker run -d --rm -v $PWD/keystore.jks:/xds/server/keystore.jks:ro `
         -v $PWD/xds-ssl-options.xml:/xds/server/xds-options.xml:ro `
         --name=xdsserver antennahouse/xdsserver:6
Parameter Description
-v %cd%\keystore.jks:/xds/server/keystore.jks:ro Mount the keystore read-only as /xds/server/keystore.jks in the Docker container
-v %cd%\xds-ssl-options.xml:/xds/server/xds-options.xml:ro Mount the Option File read-only as /xds/server/xds-options.xml in the Docker container

The SSL parameters are specified in the xds-ssl-options.xml file:

<commandLine>
  <value>-java-prop</value>
  <value>javax.net.ssl.keyStore</value>
  <value>keystore.jks</value>
  <value>-java-prop</value>
  <value>javax.net.ssl.keyStorePassword</value>
  <value>123456</value>
  <value>-ssl</value>
</commandLine>

Media files mounted on the Docker container

Media references that use the ‘file:’ protocol or that contain an absolute path are resolved as paths in the Web Interface V6.0 for AH Formatter Server container. Media files on the host machine can be mounted at those locations in the Docker container. Either directories containing media files or individual media files can be mounted on the container so that they can be found when AH Formatter V6.6 formats the document. This example (which uses Command Prompt syntax) mounts a directory containing images:

> docker run -d --rm -v %cd%\img:/img:ro ^
   --name=xdsserver antennahouse/xdsserver:6

Parameter Description
-v %cd%\img:/img:ro Mount the read-only directory containing media files at the location in the Docker container

Check that the Docker container is running

$ docker container ls
CONTAINER ID        IMAGE                       COMMAND                   CREATED             STATUS                    PORTS                              NAMES
c70ac7e48402        antennahouse/xdsserver:6    "java -jar xds-serve…"   15 minutes ago      Up 15 minutes (healthy)   0.0.0.0:9999->9999/tcp             xdsserver

Note that the container ID will be different each time that the container is run.

Stop the Docker container

$ docker container stop xdsserver

If the Docker container does not have an assigned name, then use the container ID from the output of “docker container ls”. For example:

$ docker container stop c70ac7e48402

Web Interface for AH Formatter Client

The Web Interface for AH Formatter Client may be run by any user.

Start the program

$ java -jar xds-client.jar -d in/hello-world.fo -o hello-world.pdf

Alternative host or port

The Web Interface V6.0 for AH Formatter Server may be hosted on a different machine. It may also accept connections through a different port than the default.

$ java -jar xds-client.jar -d in/hello-world.fo -o hello-world.pdf \
    -xds-host localhost -xds-port 9999

Parameter Description
-xds-host localhost Hostname or IP address of the Web Interface V6.0 for AH Formatter Server machine
-xds-port 9999 Connection port of the Web Interface V6.0 for AH Formatter Server

SSL with Java system properties

Java system properties for the keystore location and password may be specified on the java command line before the ‘-jar xds-client.jar’ parameter.

  • Bash:
    $ java -Djavax.net.ssl.trustStore=`pwd`/keystore.jks \
         -Djavax.net.ssl.trustStorePassword=123456 \
         -jar xds-client.jar -xds-ssl -d in/hello-world.fo -o hello-world.pdf
  • Command Prompt:
    > java -Djavax.net.ssl.trustStore=%cd%\keystore.jks ^
         -Djavax.net.ssl.trustStorePassword=123456 ^
         -jar xds-client.jar -xds-ssl -d in/hello-world.fo -o hello-world.pdf
  • Power Shell:
    > java -Djavax.net.ssl.trustStore=$PWD/keystore.jks `
         -Djavax.net.ssl.trustStorePassword=123456 `
         -jar xds-client.jar -xds-ssl -d in/hello-world.fo -o hello-world.pdf
Parameter Description
-Djavax.net.ssl.trustStore=`pwd`/keystore.jks Location of the keystore on the client machine
-Djavax.net.ssl.trustStorePassword=123456 Keystore password
-xds-ssl Enable use of SSL

SSL with -xds-java-prop parameters

The Java system properties for the keystore location and password may instead be specified using -xds-java-prop parameters of the Web Interface for AH Formatter Client.

  • Bash:
    $ java -jar xds-client.jar -xds-ssl \
         -xds-java-prop javax.net.ssl.trustStore `pwd`/keystore.jks \
         -xds-java-prop javax.net.ssl.trustStorePassword 123456 \
         -d in/hello-world.fo -o hello-world.pdf
  • Command Prompt:
    > java -jar xds-client.jar -xds-ssl ^
         -xds-java-prop javax.net.ssl.trustStore %cd%\keystore.jks ^
         -xds-java-prop javax.net.ssl.trustStorePassword 123456 ^
         -d in/hello-world.fo -o hello-world.pdf
  • Power Shell:
    > java -jar xds-client.jar -xds-ssl `
         -xds-java-prop javax.net.ssl.trustStore $PWD/keystore.jks `
         -xds-java-prop javax.net.ssl.trustStorePassword 123456 `
         -d in/hello-world.fo -o hello-world.pdf
Parameter Description
-xds-ssl Enable use of SSL
-xds-java-prop javax.net.ssl.trustStore $PWD/keystore.jks Location of the keystore on the client machine
-xds-java-prop javax.net.ssl.trustStorePassword 123456 Keystore password

SSL with parameters as Option File values

If the XDS_CLIENT_CONFIG environment variable is set to the absolute location of an Option File, the Web Interface for AH Formatter Client also uses the default command line options specified in the file. The client Option File has the same format as the server Option File. The -xds-java-prop parameters for specifying the Java system properties for the keystore location and password may be included in the Option File:

<commandLine>
  <value>-xds-ssl</value>
  <value>-xds-java-prop</value>
  <value>javax.net.ssl.trustStore</value>
  <value>keystore.jks</value>
  <value>-xds-java-prop</value>
  <value>javax.net.ssl.trustStorePassword</value>
  <value>123456</value>
</commandLine>

  • Bash:
    $ export XDS_CLIENT_CONFIG=`pwd`/client-option.xml
    $ java -jar xds-client.jar -d in/hello-world.fo -o hello-world.pdf
  • Command Prompt:
    > XDS_CLIENT_CONFIG=%cwd%/client-option.xml
    > java -jar xds-client.jar -d in/hello-world.fo -o hello-world.pdf
  • Power Shell:
    > $env:XDS_CLIENT_CONFIG=$PWD/client-option.xml
    > java -jar xds-client.jar -d in/hello-world.fo -o hello-world.pdf

Folder Monitoring Service

The Folder Monitoring Service may be run by any user.

Start the program

$ java -jar xds-folder-monitor.jar monitoring monitoring/output

Parameter Description
monitoring First folder to watch
monitoring/output First output folder, which must be a subdirectory of the preceding watched folder

Alternative host or port

The Server may be hosted on a different machine. It may also accept connections through a different port than the default. To use a different host or a different port, the corresponding Web Interface V6.0 for AH Formatter Client options must be specified in either the default command file or in the command.txt file that is included in each Zip archive of target files. For example, when the contents of the command-host-port.txt file is:

ARGS = -xds-host localhost -xds-port 9999
$ java -jar xds-folder-monitor.jar  \
    -default-command-file command-host-port.txt \
    monitoring monitoring/output

Parameter Description
-default-command-file command-host-port.txt Use commands in command-host-port.txt as the default commands

SSL with Java system properties

Java system properties for the keystore location and password may be specified on the java command line before the ‘-jar xds-folder-monitor.jar’ parameter. The -xds-ssl parameter that enables SSL for the Web Interface for AH Formatter Client must be included in the ARGS parameter in a command file. For example, when command-xds-ssl.txt is:

ARGS = -xds-ssl
  • Bash:
    $ java -Djavax.net.ssl.trustStore=`pwd`/keystore.jks \
         -Djavax.net.ssl.trustStorePassword=123456 \
         -jar xds-folter-monitor.jar \
         -default-command-file command-xds-ssl.txt \
         monitoring monitoring/output
  • Command Prompt:
    > java -Djavax.net.ssl.trustStore=%cd%\keystore.jks ^
         -Djavax.net.ssl.trustStorePassword=123456 ^
         -jar xds-folder-monitor.jar ^
         -default-command-file command-xds-ssl.txt ^
         monitoring monitoring/output
  • Power Shell:
    > java -Djavax.net.ssl.trustStore=$PWD/keystore.jks `
         -Djavax.net.ssl.trustStorePassword=123456 `
         -jar xds-folder-monitor.jar `
         -default-command-file command-xds-ssl.txt `
         monitoring monitoring/output
Parameter Description
-Djavax.net.ssl.trustStore=%cd%\keystore.jks Location of the keystore on the client machine
-Djavax.net.ssl.trustStorePassword=123456 Keystore password
-default-command-file command-xds-ssl.txt Use commands in command-xds-ssl.txt as the default commands

SSL with -java-prop parameters

The Java system properties for the keystore location and password may instead be specified using -java-prop parameters of the Folder Monitoring Service. -xds-ssl must also be included in the ARGS parameter in a command file.

  • Bash:
    $ java -jar xds-folder-monitor.jar \
         -java-prop javax.net.ssl.trustStore `pwd`/keystore.jks \
         -java-prop javax.net.ssl.trustStorePassword 123456 \
         -default-command-file command-xds-ssl.txt \
         monitoring monitoring/output
  • Command Prompt:
    > java -jar xds-folder-monitor.jar ^
         -java-prop javax.net.ssl.trustStore %cd%\keystore.jks ^
         -java-prop javax.net.ssl.trustStorePassword 123456 ^
         -default-command-file command-xds-ssl.txt ^
         monitoring monitoring/output
  • Power Shell:
    > java -jar xds-folder-monitor.jar `
         -java-prop javax.net.ssl.trustStore $PWD/keystore.jks `
         -java-prop javax.net.ssl.trustStorePassword 123456 `
         -default-command-file command-xds-ssl.txt `
         monitoring monitoring/output
Parameter Description
-java-prop javax.net.ssl.trustStore $PWD/keystore.jks Location of the keystore on the client machine
-java-prop javax.net.ssl.trustStorePassword 123456 Keystore password
-default-command-file command-xds-ssl.txt Use commands in command-xds-ssl.txt as the default commands

SSL with all parameters in command file

Instead of the -java-prop parameters on the Folder Monitoring Service command line, the corresponding -xds-java-prop parameter may be used in the command file. For example, when command-xds-ssl-java-prop.txt is:

ARGS = -xds-ssl
ARGS = -xds-java-prop javax.net.ssl.trustStore C:/path/to/keystore.jks
ARGS = -xds-java-prop javax.net.ssl.trustStorePassword 123456
  • Bash:
    $ java -jar xds-folder-monitor.jar \
         -default-command-file command-xds-ssl-java-prop.txt \
         monitoring monitoring/output
  • Command Prompt:
    > java -jar xds-folder-monitor.jar ^
         -default-command-file command-xds-ssl-java-prop.txt ^
         monitoring monitoring/output
  • Power Shell:
    > java -jar xds-folder-monitor.jar `
         -default-command-file command-xds-ssl-java-prop.txt `
         monitoring monitoring/output
Parameter Description
-default-command-file command-xds-ssl-java-prop.txt Use commands in command-xds-ssl-java-prop.txt as the default commands

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.

If SSL is used and the SSL parameters are specified on the command line, then the SSL parameters may be visible to other processes on the machine. The command-line parameters are also logged when the logging level is DEBUG. If the SSL parameters are specified in an Option File, then the parameters may be visible to other processes that have permission to access that file.