Public Repository

Last pushed: 7 days ago
Short Description
OpenLink Virtuoso Enterprise Edition v8.2 Docker Image
Full Description

OpenLink Virtuoso Enterprise Edition 8.2 Docker Image

Copyright (C) 2018 OpenLink Software

QuickStart Guide

Downloading the image

To pull the latest Virtuoso 8.2 docker) image to your local system, you can use the following command: 

$ docker pull openlink/virtuoso-closedsource-8

To check the version of the Virtuoso binary, you can use the following command:

$ docker run openlink/virtuoso-closedsource-8 version

This Docker image is using the following version of Virtuoso:

OpenLink Virtuoso Universal Server (Enterprise Edition)
Version 08.02.3309-pthreads as of Oct 31 2018 (30fcb64)
Compiled for Linux (x86_64-generic-linux-glibc25)
Hosted Runtime Environments:  VDB
Copyright (C) 1998-2018 OpenLink Software

Creating a sample Virtuoso instance

Here is a quick example of how to create a new virtuoso instance on your system:

$ mkdir my_virtdb
$ cd my_virtdb
$ docker run \
    --name my_virtdb \
    --interactive \
    --tty \
    --env DBA_PASSWORD=mysecret \
    --publish 1111:1111 \
    --publish  8890:8890 \
    --volume `pwd`:/database \
    openlink/virtuoso-closedsource-8:latest

This will create a new Virtuoso database in the my_virtdb subdirectory and starts a Virtuoso instance with the HTTP server listening on port 8890 and the ODBC / JDBC / ADO.Net / OLE-DB / ISQL data server listening on port 1111.

The docker) image in running in foreground (with -i or --interactive) mode, so you can see what it is doing.

You should now be able to contact the Virtuoso HTTP server using the following URL:

http://localhost:8890/

You can shut down Virtuoso by pressing the CTRL and C buttons in that terminal session.

Licensing

If the Virtuoso binary cannot find a license, it will start with a restrictive courtesy license license which allows a small number of concurrent ODBC / JDBC / ADO.Net / OLE-DB / ISQL connections, with a low size limit on the maximum number of rows that can be retrieved in a query result-set, and terminates the instance after 10 minutes of use.

To unlock the full potential of Virtuoso, you can obtain a FREE Evaluation License via our License Generator Web Service.

Naturally, following successful evaluation, you can choose from a variety of commercial edition licenses from our online shop or contact us (or your account manager) directly for more specialized Enterprise and/or VAR/ISV/OEM licenses.

Place the resulting virtuoso.lic file in the newly created database/ directory alongside the
virtuoso.ini on your local filesystem, so the docker image can pick it up on the next startup:

$ docker cp virtuoso.lic my_virtdb:/database
$ docker stop my_virtdb
$ docker start my_virtdb

Passwords

When a new database is created, the docker image will use the Environment settings DBA_PASSWORD and DAV_PASSWORD to set passwords for the dba and dav user accounts.

If the DBA_PASSWORD Environment variable is not set, a random password will be assigned to the dba user account, and stored on the internal docker filesystem as /settings/dba_password.

If the DAV_PASSWORD Environment variable is not set, it will be set to the DBA_PASSWORD and stored as /settings/dav_password.

These files will only be readable by the user that started the image. Commands like the following may be used to reveal the randomised passwords:

$ docker exec -i -t my_virtdb cat /settings/dba_password

Without this password, you will not be able to log in to the dba account using either the isql tool or the Virtuoso Conductor.

NOTE: Users are advised to immediately change the password and then remove this file from the filesystem.

Persistent storage

In order to retain changes to the Virtuoso database, the database documents should be stored on the host file system.

The docker) image exposes a /database volume that can be easily mapped to a local directory on the filesystem. If this directory is empty, the docker image will put an
initial virtuoso.ini into the mapped directory and then proceeds to create a new database.

Stopping the image

When the docker) image is running in foreground mode (with -i or --interactive), you can shut down Virtuoso by pressing the CTRL and C buttons in that terminal session. You can also use the following command on a different terminal:

$ docker stop my_virtdb

Restarting the image

Once the docker) image has been registered with the docker run or docker create command on your local system, you can start it in the background using:

$ docker start my_virtdb

If you prefer to run the instance in foreground mode, you can use:

$ docker start -i -a my_virtdb

Checking the startup log

If the docker) image is started in background (without -i or --interactive) mode, you can look at the recent output of the virtuoso process by running:

$ docker logs my_virtdb

Using isql to connect

To connect to your running Virtuoso instance, you can use the following command:

$ docker exec -i my_virtdb isql 1111

You will be prompted for the dba account password.

NOTE: If you provide an incorrect password multiple times, Virtuoso will lock the dba account
for a couple of minutes.

Using an existing database

If the mapped directory contains a virtuoso.ini and accompanying database documents, the new docker) image will attempt to use these.

NOTE: Directory paths referenced in the virtuoso.ini should be relative to the internal
directory structure of the docker) image in order to work.

OpenLink Virtuoso Enterprise Edition 8.2 Docker Reference

Identifier
https://kidehen3.solid.openlinksw.com:8444/public/dokieli-stuff/virtuoso-ent-docker.html
Derived From
https://hub.docker.com/r/openlink/virtuoso-closedsource-8/
Derived On

Downloading the image

To pull the latest Virtuoso 8.2 docker) image to your local system, you can use the following command: 

$ docker pull openlink/virtuoso-closedsource-8

To check the version of the Virtuoso binary, you can use the following command:

$ docker run openlink/virtuoso-closedsource-8 version

This Docker image is using the following version of Virtuoso:

OpenLink Virtuoso Universal Server (Enterprise Edition)
Version 08.02.3309-pthreads as of Oct 31 2018 (30fcb64)
Compiled for Linux (x86_64-generic-linux-glibc25)
Hosted Runtime Environments:  VDB
Copyright (C) 1998-2018 OpenLink Software

Configurable resources

The OpenLink Virtuoso Enterprise Edition docker image exposes a number of resources that can be configured or mapped to the local machine.

Ports

Port 1111

This port can be mapped to provide external access to the docker) image to connect using any of the
Virtuoso client providers such as ODBC, JDBC, ADO.Net, OLE-DB, iSQL from either the host
system or from another docker image.

In case you want to run multiple docker) images on the same host system you can use the -p or
--publish command-line option to map a free port on the local system (e.g. 1112) to the default
isql port 1111 on the docker) system.

$ docker create .....
  ...
  --publish 1112:1111 \
  ...

Port 8890

This port can be mapped to provide external access to the Virtuoso HTTP server.

In case you want to run multiple docker images on the same host system you can use the -p or
--publish command-line option to map a free port on the local system. E.g. if you want this image
to be the default web-server, you can map port 80 on the host to the default HTTP port 8890 on
the docker) system.

$ docker create .....
  ...
  --publish 80:8890 \
  ...

As soon as the docker) image has been started you can connect to Virtuoso using the following URL in
your browser:

http://localhost/

Volume(s)

/database

This volume contains the virtuoso.ini, virtuoso.lic and all the files used by the Virtuoso database.

When creating or running any docker) container there are two parameters that play an important role in data persistence:

  • Named vs Unnamed containers (using the -n or --name argument)

  • Mapped or Unmapped volumes (using the -v or --volume argument)

If you create a docker) image without specifying either a name for the resulting (unnamed) container and a volume mapping, this docker) image will be destroyed the moment the container is stopped and while the directory is not immediately removed from the host filesystem, it may not be easy to locate and recover any data inside.

As long as you at least use the --name argument, the docker container can be stopped and restarted without any loss of data.

If you create a docker) image without mapping a volume to a local directory on your hard drive, the docker) system will create a directory within its own filesystem which maybe on your root filesystem (on Linux docker) images are located under /var/lib/docker/containers). This can cause problems if the filesystem is not large enough or when you want to change to a newer version of the image without loosing your existing data. Using an unnamed volume also causes problems when you want to upgrade to a later version of the docker) image while keeping your existing database.

While there are circumstances where you may prefer an unnamed container with mapped volume, we recommend you use both --name and --volume parameters on all virtuoso containers you create.

Environment variables

DBA_PASSWORD_FILE

This environment variable should be set in combination with one of the secure options to pass
sensitive information to the docker) image. The startup script will read the content from this file
on the internal docker) filesystem and assign it to the DBA_PASSWORD environment variable
internally. In this case the DBA_PASSWORD setting is not recorded in the meta data of this docker
instance.

Example:

$ echo -n 'verysecretpw' | docker secret create dba_secret -

$ docker service create .... \
    ...
    --secret dba_secret \
    --env DBA_PASSWORD_FILE=/run/secrets/dba_secret \
    ...

See also:

DAV_PASSWORD_FILE

See DBA_PASSWORD_FILE for more details.

DBA_PASSWORD

If this environment variable is set via either the command-line options -e, --env, --env-file
or via the environment section in a .yml file, the value will be assigned as the initial
password of the dba account when creating a new database.

If this variable is set to ami-id the docker image will attempt to get this value from the EC2
registry on the Amazon AMI. If this fails or if this docker) container is not started on an
AMI the variable will be regarded as unset.

If this variable is unset, a random password will be generated and assigned as the initial
password of the dba account when creating a new database.

The password will be stored inside the docker container in /settings/dba_password and we recommend
you remove this file after you have changed the dba password to some other value, either via the
conductor web interface, or via the isql command.

Example:

$ docker create .....
  ...
  --env DBA_PASSWORD=mysecret \
  ...

NOTE: As environment variables are stored in the meta information of the docker) image, the
initial password is easily visible to all users on the same machine that are able to run the docker inspect command. In cases where this could be an issue we recommend using the 'docker secrets'
option in combination with the DBA_PASSWORD_FILE option.

DAV_PASSWORD_FILE

See DBA_PASSWORD_FILE for more details.

DAV_PASSWORD

If this environment variable is set via either the command-line options -e, --env, --env-file
or via the environment section in a .yml file, the value will be assigned as the initial
password of the dav account when creating a new database.

If this variable is not set, the value of the DBA_PASSWORD setting will be used for both dba
and dav accounts.

The password will be stored inside the docker) container in /settings/dav_password and we recommend
you remove this file after you have changed the dav password to some other value, either via the
conductor web interface, or via the isql command.

VIRTUOSO_LIC_FILE

This environment variable is used in combination with one of the secure options to pass sensitive
information to the Virtuoso closed source docker) images. The startup script will read the content
from this file on the internal docker filesystem and copy it to the /database/virtuoso.lic file.

See also:

VIRTUOSO_INI_FILE

This environment variable is used in combination with one of the following options to pass
information to the docker) image. The startup script will read the content of this file on the
internal docker filesystem and copy it to the '/database/virtuoso.inifile, instead of installing the defaultvirtuoso.ini` file from the virtuoso installation.

Please note that all path settings in virtuoso.ini should be based on the internal
filesystem structure of the docker) image, and not refer to directory paths on the host system. It is
possible to bind additional directories from the host system into the docker) instance using bind mounts using command-line options such as --mount`

After installing a virtuoso.ini file, the startup script will parse the environment variables to
allow additional updates to the virtuoso.ini file as detailed in the next paragraph.

See also:

Updating virtuoso.ini via environment settings

Using environment variables when creating the Virtuoso docker) instance via the command-line options
-e, --env, --env-file or via the environment section in a .yml file, you can add or
overrule any parameter within the virtuoso.ini file.

These environment variables must be named like:

VIRT_SECTION_KEY=VALUE

where

  • VIRT is common prefix to group such variables together (always in upper case)
  • SECTION is the name of the [section] in virtuoso.ini (case insensitive)
  • KEY is the name of a key within the section (case insensitive)
  • VALUE is the text to be written into the key (case sensitive)

The SECTION and KEY parts of these variable names can be written in either uppercase (most
commonly used) or mixed case, without having to exactly match the case used inside the virtuoso.ini
file. There is no validation on the SECTION and KEY name parts, so any mistake may result in a
non-functional setting.

The following names all refer to the same setting:

  • VIRT_Parameters_NumberOfBuffers (case matching the section and key name in virtuoso.ini)
  • VIRT_PARAMETERS_NUMBEROFBUFFERS (recommended way to name environment variables)
  • VIRT_parameters_numberofbuffers (optional)

The VALUE is case sensitive string and should be surrounded by either single (`) or double (")
quotes in case there are spaces or other special characters in the string.

Example:

$ docker create .... \
  ... \
  -e VIRT_PARAMETERS_NUMBEROFBUFFERS=1000000 \
  -e VIRT_HTTPSERVER_MaxClientConnections=100 \
  -e VIRT_HTTPSERVER_SSL_PROTOCOLS="TLS1.1, TLS1.2" \
  ...

Please note that all path settings in virtuoso.ini should be based on the internal
filesystem structure of the docker image, and cannot directly refer to directory paths on the host
system. It is possible to bind additional directories from the host system into the docker) instance
using bind mounts using command-line options such as --mount`.

See also:

Docker Pull Command
Owner
openlink