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