11. RDFox Docker Images¶

This section documents the official Docker images for RDFox which are publically available from Docker Hub repository oxfordsemantic/rdfox.

The defaults of the RDFox Docker images are described in the next section, followed by a section describing suggested approaches for mounting the RDFox license key, server directory and shell root directory. The final section provides a selection of example docker run commands for starting RDFox containers. The only pre-requisite for running these is a Docker installation for your platform. See the official Docker installation page for instructions.

The documentation assumes familiarity with the basics of Docker in general and in particular the different ways of mounting storage into containers with the desired container-side permissions.

Note

For readability, short-form (-v) mount arguments will be used throughout but readers should be aware that the official Docker documentation recommends the long-form (--mount) alternative.

11.1. Image Defaults¶

Default values for the official RDFox Docker images are described below. It is possible to override all of these defaults but, for simplicity, the documentation of each assumes the other defaults are being used.

User: The default user within the images is rdfox. This determines the default server directory path within containers as /home/rdfox/.RDFox.
Entrypoint: The default entry point for the images is the RDFox executable embedded at container path /opt/RDFox/RDFox. The version of the executable at this path will match the version in the tag for the image.
Command: The default command is daemon. This can be overridden with any valid RDFox command (see Section 10.1).
Working directory: The default working directory for the images is /data. This has no impact when starting in daemon mode but will be the default root directory when using the RDFox shell.
Ports: The images expose the default port for the RDFox endpoint: 12110.
Required superuser capabilities: In the interests of security, images in the oxfordsemantic/rdfox repository have been designed to run with no superuser capabilities (see Linux kernel capabilities). The inclusion of the argument --cap-drop ALL in docker run commands, or the equivalent in other environments, is recommended when launching images in the above repository. By contrast, companion images (see Section 11.2.2 below) must be run as root with at least the CAP_CHOWN capability which they use to ensure that the rdfox user within the main images will have access to the mounted server directory.

11.2. Suggested Mounts¶

The following section provides suggestions on how to mount key data or storage into RDFox containers.

11.2.1. Mounting the License Key¶

Although various solutions to injecting the RDFox license key are possible, the recommended approach is to mount a valid, in-date license key file to container path /opt/RDFox/RDFox.lic. This will enable the containerised RDFox process to locate the license without requiring additional command line arguments whilst ensuring that the license key need not be stored within the server directory.

If using the images in Kubernetes, where the RDFox license key may be held as a Secret resource, mounting the secret as described above will hide the image’s entry-point executable, leading to a failure to start. In this situation, mapping the secret into the container’s environment via variable RDFOX_LICENSE_CONTENT is the next most convenient option.

Either of the methods described above may be used with both the oxfordsemantic/rdfox images and their oxfordsemantic/rdfox-init companions.

11.2.2. Preparing and Mounting the Server Directory Volume¶

When RDFox is configured to persist roles and data stores, it does so inside the configured server directory. As described above, the default server directory path for oxfordsemantic/rdfox images is /home/rdfox/.RDFox. For use cases where persistence is enabled it is therefore most convenient to mount storage to that container path, usually but not necessarily in the form of a Docker volume.

It is important to ensure that the rdfox user can read and write the storage mounted as the server directory. In order to start RDFox in daemon mode with persistence enabled, it is also recommended that users initialize access control within the server directory before mounting it into their oxfordsemantic/rdfox container. To make this easier, a companion initialization image for each image in oxfordsemantic/rdfox is hosted in repository oxfordsemantic/rdfox-init with a matching tag. For example, the image oxfordsemantic/rdfox:3.1.1 has companion oxfordsemantic/rdfox-init:3.1.1.

The following command creates a Docker volume with name rdfox-server-directory (assuming no such volume exists already). This includes ensuring that the rdfox user is the owner of the directory and its content, and initializing access control with the role name and password held in the environment via variables RDFOX_ROLE and RDFOX_PASSWORD respectively. The parameter <path-to-license-file> must be an absolute path to a valid, in-data RDFox license key file.

docker run --rm -v <path-to-license-file>:/opt/RDFox/RDFox.lic -v rdfox-server-directory:/home/rdfox/.RDFox -e RDFOX_ROLE -e RDFOX_PASSWORD oxfordsemantic/rdfox-init

If the shell script within the resulting container finds a file at path /data/initialize.rdfox, it will pass this as an argument to the initializing RDFox process which will then run the file as an RDFox script. Users can exploit this to include data store creation and population in their initialization step. See the following section for advice on mounting storage as the shell root directory to achieve this.

Note

In order to change the ownership of the mounted storage and then run RDFox as the right user, companion images must be started as root (their default user) with capabilities CAP_CHOWN, CAP_SETUID and CAP_SETGID.

11.2.3. Mounting the Shell Root Directory¶

Often, when developing applications for RDFox it is convenient to keep the rules, base facts and shell scripts for the application in a single directory. When using the RDFox shell in Docker, this directory must be mounted into the container’s file system with the appropriate permissions to allow the rdfox user to read and write as necessary.

Users are free to use either a named volume or a bind mount for the shell root directory. Bind mounting a host directory will often be more convenient for this purpose however named volumes offer more flexibility to achieve the necessary container-side permissions, particularly where the Docker client is on Windows. The most convenient target path for the mount is the default working directory /data as this is the default value for the shell root variable.

11.3. Example Commands¶

The example commands in this section demonstrate how to run RDFox Docker images in several different configurations, starting with the simplest possible and progressing to more realistic scenarios. With the appropriate substitutions, the commands should work on any operating system where the Docker CLI is supported.

In all of the examples, <path-to-license-file> should be replaced with an _absolute_ path to a valid, in-date RDFox license key file.

11.3.1. Running Interactively with no Persistence or Endpoint¶

The simplest possible docker run command to launch RDFox in a container is:

docker run -it -v <path-to-license-file>:/opt/RDFox/RDFox.lic oxfordsemantic/rdfox sandbox

This will start the RDFox shell for interactive usage but is not very useful. First of all, nothing from the session will be persisted since no server directory has been mounted and the image default daemon command has been overridden with sandbox mode thereby disabling role and data store persistence. Second, since no storage has been mounted to the /data path, there is no possibility of importing from or exporting to the host filesystem using the shell, and we have no access to any shell scripts. Finally, since we did not publish the 12110 port it will be impossible to reach the RDFox endpoint from outside the container even if it is started using endpoint start. Nevertheless, this command may be useful for quickly testing out RDFox functionality on data and rules simple enough to be typed (or pasted) in.

The remaining commands in this section demonstrate ways to alleviate the restrictions described for the above command at the cost of additional arguments.

11.3.2. Running Interactively With Persistence¶

To run interactively users must include the -i and -t arguments to docker run and override the default daemon command with shell. Using a volume, <server-directory-volume>, prepared as described in Section 11.2.2, and the absolute path, <shell-root-directory>, to a directory containing files we want to use in the shell, the following command will start the RDFox shell inside a container with both role and data store persistence enabled:

docker run -it --cap-drop ALL
           -v <path-to-license-file>:/opt/RDFox/RDFox.lic \
           -v <server-directory-volume>:/home/rdfox/.RDFox \
           -v <shell-root-directory>:/data \
           oxfordsemantic/rdfox shell

11.3.3. Running in `daemon` Mode With Persistence¶

The defaults for the oxfordsemantic/rdfox images have been optimised for running in daemon mode with both role and data store persistence enabled. Using a volume, <server-directory-volume>, prepared as described in Section 11.2.2, a containerised RDFox daemon, reachable at host port <host-port>, can be launched using the following command:

docker run -d --cap-drop ALL -p <host-port>:12110 \
           -v <path-to-license-file>:/opt/RDFox/RDFox.lic \
           -v <server-directory-volume>:/home/rdfox/.RDFox \
           oxfordsemantic/rdfox

11.3.4. Running in `daemon` Mode With No Persistence¶

To run as a purely in-memory data store, where all interaction will be via the RDFox endpoint, it is possible to supply the name and password of the first role via environment variables in order to initialize access control without any interaction via standard input and output. Assuming variables RDFOX_ROLE and RDFOX_PASSWORD have been defined in the environment where the command will run, a containerised RDFox daemon with no persistence, reachable at host port <host-port>, can be launched using the following command:

docker run -d --cap-drop ALL -p <host-port>:12110 -e RDFOX_ROLE -e RDFOX_PASSWORD \
           -v <path-to-license-file>:/opt/RDFox/RDFox.lic \
           oxfordsemantic/rdfox -persist-roles off -persist-ds off daemon

The RDFox server started by the above command will contain no data stores initially. These can be created and populated via the REST API however, in some situations, it may be desirable to do this directly using an RDFox shell script. Given a startup script start.rdfox in host directory <shell-root-directory>, a containerised RDFox daemon with no persistence, initialized by the script and reachable at host port <host-port>, can be launched using the following command:

docker run -d --cap-drop ALL -p <host-port>:12110 -e RDFOX_ROLE -e RDFOX_PASSWORD \
           -v <path-to-license-file>:/opt/RDFox/RDFox.lic \
           -v <shell-root-directory>:/data \
           oxfordsemantic/rdfox -persist-roles off -persist-ds off shell . start

To prevent RDFox from exiting after executing the shell script, and to ensure that the endpoint is running, the script should conclude with the daemon command (see Section 10.2.2.9).