Warning: This document is for an old version of RDFox. The latest version is 7.2.

22. RDFox Docker Images

This section documents the official Docker images for RDFox, which are publicly available from Docker Hub repository oxfordsemantic/rdfox, and their companion images in repository oxfordsemantic/rdfox-init.

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 running the images. 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.

22.1. Image Defaults

Default values for the images in the oxfordsemantic/rdfox repository 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 request-logger elf. This can be overridden with any valid RDFox command (see Section 18).

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.

22.2. Suggested Mounts

The following sections provide suggestions on how to mount the license key, how to mount and initialize storage for the server directory and how to mount storage for the shell root directory.

22.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 containerized 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.

The methods described above work for both oxfordsemantic/rdfox and oxfordsemantic/rdfox images.

22.2.2. Mounting the Server Directory

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, whether a host directory or Docker volume, to that container path. If for any reason the server directory must be mounted to a different container path, the default command for the image must be overridden with a valid RDFox command which includes the -server-directory parameter specifying the container-side server directory path.

Wherever the storage is mounted, it must be readable and writable by the user that launches RDFox within the container (the rdfox user by default). In order to start RDFox in daemon mode without having to supply a role name and password, it is also necessary that users have previously initialized access control within the server directory (see Section 12.2.1 for more information about initialization). The companion images described in the next section can help to prepare new server directories in order to meet all of these requirements.

22.2.2.1. Initializing the Server Directory with a Companion Image

To simplify the initialization of new server directories, each image in the oxfordsemantic/rdfox repository has a companion image with a matching tag in the oxfordsemantic/rdfox repository. The purpose of these images is to prepare a mounted volume as a server directory for a long-lived container that will use the corresponding oxfordsemantic/rdfox image.

Since initialization requires root privileges to ensure the correct file system access rights, as well as a plaintext password to initialize RDFox’s access control system, using a companion image to prepare the server directory for a long-lived RDFox container allows the latter to be run in a more secure environment. Specifically, the long-lived container can be launched as an unprivileged system account (such as the image’s default user, rdfox), all superuser capabilities can be dropped, and no plaintext password is needed for the first RDFox server role.

When run against a completely uninitialized server directory, companion images perform the following steps:

  1. ensure that the storage is owned by the rdfox user and is readable and writable by that user

  2. invoke RDFox to initialize access control and, optionally, execute a user-supplied RDFox shell script

  3. check that access control settings have been written to the disk.

Step 1 requires that the container is launched as root with at least the capabilities CAP_CHOWN, CAP_SETUID and CAP_SETGID. Step 2 requires an RDFox license key as well as the name and password of the first role for RDFox. These can be supplied using the same command line arguments and environment variables as the main oxfordsemantic/rdfox images.

Companion images accept the following subset of RDFox’s supported command line parameters:

  • -api-log {on|off}

  • -api-log.directory <api-log-directory>

  • -api-log.input-recording-limit <recording-limit>

  • -license-content <license-content>

  • -license-file <license-file>

  • -password <role-password>

  • -persist-ds {off|file}

  • -role <role-name>

  • -server-directory <server-directory>

Server parameters specified using the above arguments will not be saved to the server directory and will have to be specified as arguments to the long-lived oxfordsemantic/rdfox container as well, if required. Server parameters that should be used for both the initializing and long-lived RDFox containers may be supplied in a server parameters file named parameters in the container’s working directory which will be copied to the server directory before RDFox is invoked.

Note

If the server parameter persist-roles is not specified in the command line arguments nor in a parameters file, no access control settings will be persisted. This will cause the companion image to return a non-zero exit code indicating failure since the server directory will remain uninitialized.

Note

It is recommended that both the persist-roles and persist-ds parameters be supplied in a parameters file since these settings must always be specified in a way that matches the persistence type in use in the directory.

In some cases it may be desirable to create and populate one or more data stores or to configure access control as part of the initialization step. To facilitate this, companion images check for a file named initialize.rdfox in the container’s working directory and, if it exists, pass it to the RDFox shell to be executed as an RDFox shell script. This can help avoid the need to do create and configure via the REST endpoint later on.

When the specified server directory already contains a roles file or directory, indicating that it has already been initialized, companion images return without invoking RDFox.

See Section 22.3 for an example Docker run command for a companion image.

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

22.3. Example Docker Run 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.

Example: 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 configured. Second, since no storage has been mounted to the /data path, there is no possibility of importing from or exporting to the host file system from the RDFox 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.

Example: Initializing a New Server Directory with a Companion Image.

The following command creates a Docker volume with name rdfox-server-directory (assuming no such volume exists already) and uses the latest oxfordsemantic/rdfox image to prepare it for use with the latest oxfordsemantic/rdfox image. Access control will be initialized with the role name and password held in the environment variables RDFOX_ROLE and RDFOX_PASSWORD respectively (these must be set in the environment where the command is run).

docker run --rm -v <path-to-license-file>:/opt/RDFox/RDFox.lic \
           -v rdfox-server-directory:/home/rdfox/.RDFox \
           -v ${PWD}/parameters:/data/parameters \
           -e RDFOX_ROLE \
           -e RDFOX_PASSWORD \
           oxfordsemantic/rdfox-init

The command relies on a file named parameters in the working directory of the host with the following content:

persist-roles file
persist-ds    file

If the resulting container exits cleanly, the rdfox-server-directory volume will be ready for use, as demonstrated in the next example.

Example: Running in Daemon Mode With Persistence

Using volume rdfox-server-directory, prepared as described in the preceding example, a containerized 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 rdfox-server-directory:/home/rdfox/.RDFox \
           oxfordsemantic/rdfox

Example: 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 as in the following command.

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

When launched this way, RDFox will always prompt for a role name and password which it will use to initialize access control if <rdfox-server-directory> has not previously been initialized, and in all cases to log into the shell.

Example: 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 containerized 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 \
           -v <path-to-license-file>:/opt/RDFox/RDFox.lic \
           -e RDFOX_ROLE \
           -e RDFOX_PASSWORD \
           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 at startup time using an RDFox shell script. Given a startup script start.rdfox in host directory <shell-root-directory>, a containerized 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 \
           -v <path-to-license-file>:/opt/RDFox/RDFox.lic \
           -v <shell-root-directory>:/data \
           -e RDFOX_ROLE \
           -e RDFOX_PASSWORD \
           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 15.2.10).

22.4. Checking the Health of RDFox Containers

Many container orchestration systems require a health check endpoint to determine whether a container is healthy. The RDFox endpoint has a dedicated API for this purpose at path /health. GET requests to this path will always return 204 - No Content. See also Section 16.17.