opal docker - pkleef/virtuoso-opensource GitHub Wiki

Creating an OPAL instance using Docker

Copyright (C) 2025 OpenLink Software [email protected]

Table of Contents

Introduction

The OpenLink Virtuoso Commercial docker image (openlink/virtuoso-commercial-8) allows users to run a combination of shell scripts and SQL scripts to initialize a new database.

This example shows how a Virtuoso Docker instance, started by the docker compose command, can install the OpenLink Personal Assistant layer (OPAL) and related VAD packages.

This example has been tested on both Ubuntu Noble Numbat 24.04 (x86_64) and macOS Big Sur 11.6 (x86_64 and Apple Silicon).

Most modern Linux distributions provide Docker packages as part of their repository.

For Apple macOS and Microsoft Windows Docker installers can be downloaded from the Docker website.

Note: Installing software like git, Docker and Docker Compose is left as an exercise for the reader.

Downloading and Running the Example

The source code for this example can be cloned from its repository on GitHub using the following command:

$ git clone https://github.com/OpenLinkSoftware/virtuoso-opal-docker

Starting the Example for the first time

The first time, start this example using the following commands:

$ cd virtuoso-opal-docker
$ docker compose pull
$ docker compose up

Note: On older releases of Docker you need to use the docker-compose command.

The first time it takes a minute or two to initialize the database, load all the packages and finish by starting up the instance after which you the engine is online listening for requests:

virtuoso-opal-docker-virtuoso_db-1  | 13:19:46 SSL server online at 1112
virtuoso-opal-docker-virtuoso_db-1  | 13:19:46 HTTP Server threads exceed the number of licensed connections. Setting to 1
virtuoso-opal-docker-virtuoso_db-1  | 13:19:46 HTTP/WebDAV server online at 8890
virtuoso-opal-docker-virtuoso_db-1  | 13:19:46 HTTPS server online at 8891
virtuoso-opal-docker-virtuoso_db-1  | 13:19:46 Server online at 1111 (pid 1)

At this point, you can use a browser to connect to the local OPAL endpoint using https:

https://{CNAME}:8891/chat

where {CNAME} is either the name the machine on which you installed docker, or localhost if your docker instance and browser are running on the same machine.

As this instance is using a Self-Signed SSL Certificate your browser will show a warning screen, which allows you to 'Proceed to {CNAME} (unsafe)`

Once the OPAL chat page is loaded, press the login button, login with your dba account and autorise the app to use this account.

Next enter your OpenAI API key, press the Set button and you are ready to use the OpenLink Personal Assistant.

To stop Virtuoso, you can press the CTRL-C keys in your terminal window:

$ docker compose stop

Start this Docker instance in the background

This Docker instance is set up to write the database to your hard disk in the database directory. You can start and stop it as many times as you want in the background:

$ cd virtuoso-opal-docker
$ docker compose up -d

Stop this Docker Instance

$ cd virtuoso-opal-docker
$ docker compose down

Description of Files and Directories

The docker-compose.yml File

version: "3.3"
services:
  virtuoso_db:
    image: openlink/virtuoso-closedsource-8
    volumes:
      - ./scripts:/opt/virtuoso/initdb.d
      - ./database:/database
    environment:
      - DBA_PASSWORD=dba
    ports:
      - "1111:1111"
      - "1112:1112"
      - "8890:8890"
      - "8891:8891"

The scripts Directory

This directory can contain a mix of shell (.sh) scripts and Virtuoso PL (.sql) scripts that can perform functions such as:

  • Installing additional Ubuntu packages.
  • Loading data from remote locations such as Amazon S3 buckets, Google Drives, or other locations.
  • Bulk loading data into the Virtuoso database.
  • Installing additional VAD packages into the database.
  • Adding new Virtuoso users.
  • Granting permissions to Virtuoso users.
  • Regenerating freetext indexes or other initial data.

The scripts are run only once during the initial database creation; subsequent restarts of the Docker image will not cause these scripts to be rerun.

The scripts are run in alphabetical order, so we suggest starting the script name with a sequence number, to make the ordering explicit.

For security purposes, Virtuoso will run the .sql scripts in a special mode and will not respond to connections on its SQL (1111) and/or HTTP (8890) ports.

At the end of each .sql script, Virtuoso automatically performs a checkpoint to make sure the changes are fully written back to the database. This is very important for scripts that use the bulk loader function rdf_loader_run() or for any reason manually change the ACID mode of the database.

After all the initialization scripts have run to completion, Virtuoso will be started normally and start listening to requests on its SQL (1111), SQL SSL (1112), HTTP (8890), and HTTPS (8891) ports.

The scripts/10-init-opal.sql File

This script installs the following VAD packages into a new database:

  • OpenLink Virtuoso Faceted Browser (FCT)
  • OpenLink Virtuoso Authentication Layer (VAL)
  • OpenLink Personal AI Layer (OPAL)
--
--  Copyright (C) 2025 OpenLink Software
--


VAD_INSTALL ('../vad/fct_dav.vad');
VAD_INSTALL ('../vad/val_dav.vad');
VAD_INSTALL ('../vad/personal_assistant_dav.vad');

--
--  End of script
--