Web Interface for Formatter Server Docker Image

The Docker image for the combination of Web Interface V6.0 for Formatter Server and Linux Antenna House Formatter V7.3, Formatter V7.2, Formatter V7.1, Formatter V7.0 or 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 Formatter Server and the Linux Antenna House Formatter V7.3, V7.1, V7.0 or V6.6. The Web Interface V6.0 for Formatter Server in the Docker container will run only when both licenses are found.

Version Information

The tags of the Docker image indicate the version of the Linux Antenna House Formatter V7.3or 64-bit Linux V7.2, , V7.1, V7.0 or V6.6 that is bundled with Web Interface V6.0 for Formatter Server. (The ‘ahfcmd73’ Docker image, etc. for the Antenna House Formatter 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 Formatter Server and the Linux Antenna House Formatter V7.3, Formatter V7.2, V7.1, V7.0 or 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 Antenna House Formatter V7.3, V7.2, V7.1, V7.0 or 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. The Docker image, which is tagged with the ‘latest’, major and point release numbers on Docker Hub, will be replaced with the latest image with each maintenance release. The following table illustrates which tags will change over a series of releases:

Formatter version Docker tags
latest Major version Major + Point Major + Point + Maintenance Build
V7.3 R1 latest 7 7.3 7.3.0 7.3.1.598881
V7.3 MR1 7.3.1 7.3.x.xxxxx

Labels

Use “docker inspect” to obtain the version information for the Antenna House Formatter V7.3, V7.2, V7.1, V7.0 or V6.6 in the Docker image:

$ docker inspect --format='{{.Config.Labels.about}}' antennahouse/xdsserver:7
AHFCmd : Antenna House Formatter V7.3 R1 Linux : 7.3.1.59888 (2023-01-19T09:42+09)

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

$ docker inspect --format='{{.Config.Labels.xdsserverabout}}' antennahouse/xdsserver:7
xds version: 6.0MR10 (386) 2023-01-25 14:14 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:7’ or ‘antennahouse/xdsserver:7.3’, 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:7
7: Pulling from docker.io/antennahouse/xdsserver
be8881be8156: Pull complete 
87afd40ffc1e: Pull complete 
46c26bf1484f: Pull complete 
6f4da1ccc624: Pull complete 
d80f886906c8: Pull complete 
6bd436e56012: Pull complete 
65c630b63cb5: Pull complete 
88db1ec641e8: Pull complete 
d4e808e65d22: Pull complete 
991742fff373: Pull complete 
8d0575674291: Pull complete 
6d06c9f3bb07: Pull complete 
03077647109d: Pull complete 
9079e7be1a9e: Pull complete 
Digest: sha256:cf50f68357b42988ea023e92a99d082e400ae4f5c190929c566c9084c0628e07
Status: Downloaded newer image for docker.io/antennahouse/xdsserver:7

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 Formatter Server and an ‘AHFormatter.lic’ file for Antenna House Formatter V7.3, V7.2, V7.1, V7.0 or 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:

Contents of the Web Interface Server licenses zip file

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 Formatter Server and the Antenna House Formatter V7.3, V7.2, V7.1, V7.0 or V6.6 in the container use the license files in /license:

Mount the Web Interface Server licenses on the container

Option File for Web Interface V6.0 for Formatter Server

The Docker image includes a default Option File for the Web Interface V6.0 for 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 Formatter Server.

Maximum Number of Client Connections and Formatter Processes

The -mc option of Web Interface V6.0 for 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 Antenna House Formatter V7.3, V7.2, V7.1, V7.0 or 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 Antenna House Formatter V7.3, V7.2, V7.1, V7.0 or 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 Formatter Server is typically run as a detached service. The container is started by running a Docker command. The Web Interface V6.0 for 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 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 Formatter Server can either only accept unsecured connections or only accept connections that are secured using SSL. If the Web Interface V6.0 for Formatter Server is configured to use SSL, then the Web Interface V6.0 for Formatter Client or the Folder Monitoring Service must use SSL. See the SSL section of the Web Interface V6.0 for 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 Formatter Server

Web Interface for 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:7
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:7 Web Interface V6.0 for 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:7 \
         -java-prop javax.net.ssl.keyStore keystore.jks \
         -java-prop javax.net.ssl.keyStorePassword 123456 -ssl \
         -p 9999:9999 --name=xdsserver antennahouse/xdsserver:7
  • Command Prompt:

    > java docker run -d --rm -v %cd%\keystore.jks:/xds/server/keystore.jks:ro ^
         antennahouse/xdsserver:7 ^
         -java-prop javax.net.ssl.keyStore keystore.jks ^
         -java-prop javax.net.ssl.keyStorePassword 123456 -ssl ^
         -p 9999:9999 --name=xdsserver antennahouse/xdsserver:7
  • Power Shell:

    > docker run -d --rm -v $PWD/keystore.jks:/xds/server/keystore.jks:ro `
         antennahouse/xdsserver:7 `
         -java-prop javax.net.ssl.keyStore keystore.jks `
         -java-prop javax.net.ssl.keyStorePassword 123456 -ssl `
         -p 9999:9999 --name=xdsserver antennahouse/xdsserver:7
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

Web Interface Server with SSL options specified on the command line

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

Web Interface Server with SSL options specified an Option File

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 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 Antenna House Formatter V7.3 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:7
Parameter Description
-v %cd%\img:/img:ro Mount the read-only directory containing media files at the location in the Docker container

Directory containing images mounted on Docker container

Check that the Docker container is running

$ docker container ls
CONTAINER ID        IMAGE                       COMMAND                   CREATED             STATUS                    PORTS                              NAMES
c70ac7e48402        antennahouse/xdsserver:7    "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 Formatter Client

The Web Interface for 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 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 Formatter Server machine
-xds-port 9999 Connection port of the Web Interface V6.0 for 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 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 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 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 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.