17. RDFox Docker Images¶
This section documents the official Docker images for RDFox which are
publicly available from Docker Hub repository
their companion images in repository
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.
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 (
17.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
The default user within the images is
rdfox. This determines the default server directory path within containers as
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.
The default command is
daemon. This can be overridden with any valid RDFox command (see Section 16.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.
The images expose the default port for the RDFox endpoint: 12110.
- Required superuser capabilities
In the interests of security, images in the
oxfordsemantic/rdfoxrepository have been designed to run with no superuser capabilities (see Linux kernel capabilities). The inclusion of the argument
--cap-drop ALLin docker run commands, or the equivalent in other environments, is recommended when launching images in the above repository.
17.2. Suggested Mounts¶
The following section provides suggestions on how to mount key data or storage into RDFox containers.
17.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
/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
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
17.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
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 to
specify the path to the server directory within the container.
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 11.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.
18.104.22.168. 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 the same tag in
oxfordsemantic/rdfox-init repository (for example, the image
oxfordsemantic/rdfox:4.1.0 has companion
oxfordsemantic/rdfox-init:4.1.0). These images ensure that the mounted
storage is readable and writable by the
rdfox user, and also run RDFox to
initialize persistence of access control. Additionally, users can specify an
RDFox shell script to run as part of the initialization by mounting it with
initialize.rdfox in the container’s working directory (
default). This makes it possible to create and even populate one or more data
stores as part of the initialization, avoiding the need to do so via the REST
endpoint later on.
The exit code for a container using a companion image will not reflect any
failures that occur during the execution of a mounted
script. That is, the exit code will always indicate success if RDFox starts
and exits cleanly, even if every command executed in the shell fails.
In automated scenarios where it is important to have positive confirmation of each initialization action, users should avoid mounting an initialization script and instead make the equivalent calls to the RDFox endpoint.
Companion images accept the following subset of RDFox’s supported command line parameters:
The RDFox command line parameters not accepted by companion images are irrelevant for initializing server directories and specifying them, or any unrecognized parameters, will cause the container to exit before taking any action. The container will also exit before taking any action in the case that the specified server directory contains files indicating that the directory has previously been initialized.
See below for an example Docker run command for a companion image.
In order to change the ownership of the mounted storage and then run RDFox
as the right user, companion images must be started as
default user) with capabilities
17.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
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
/data as this is the default value for the shell root
17.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 mounted and the image default
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.
Example: Initializing a New Server Directory.
The following command creates a Docker volume with name
rdfox-server-directory (assuming no such volume exists already) and uses
oxfordsemantic/rdfox-init image to prepare it for use with
oxfordsemantic/rdfox image. Access control will be
initialized with the role name and password held in the environment
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 \ -e RDFOX_ROLE \ -e RDFOX_PASSWORD \ oxfordsemantic/rdfox-init
If the resulting container exits cleanly, the
volume will be ready for use, as demonstrated in the next example.
Example: Running in Daemon Mode With Persistence
<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
-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_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 22.214.171.124).
17.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
GET requests to this path will
204 - No Content. See also Section 14.13.