Deploy a local DataSHIELD server with Opal

What is Opal?

Opal is OBiBa’s core database application for epidemiological studies. Participant data, collected by questionnaires, medical instruments, sensors, administrative databases etc. can be integrated and stored in a central data repository under a uniform model. Opal is a web application that can import, process, copy data and has advanced features for cataloguing the data (fully described, annotated and searchable data dictionaries) as recommended by the Maelstrom Research group at McGill University, Canada. Opal is typically used by a research centre to analyse the data acquired from assessment centres. Its ultimate purpose is to achieve seamless data-sharing among epidemiological studies. Opal is the reference implementation of the DataSHIELD infrastructure. More information on Opal can be found in the Opal description on OBiBa.

Source: https://isglobal-brge.github.io/resource_bookdown/opal.html

Deploy Docker containers

Here we will spawn a local instance of DataSHIELD with Docker. We will assume you have installed and configured Docker on your computer; however, if that’s not the case, visit their get started with Docker page.

Setup

The easiest way to deploy DataSHIELD with docker is by cloning the following repo: FederatedMethods/datashield_dev_install. Here, you will find a step by step guide, including a very useful docker-compose.yml file, which you can use out of the box.

If you are running Linux or macOS, you can run the following commands:

git clone https://github.com/FederatedMethods/datashield_dev_install
cd datashield_pcr/docker
docker compose up -d

Then you can inspect the Docker GUI, where you should see something like the following:

Docker conf

Open connection

By default, the docker-compose.yml file in the repo above defines a demo user, demo_user, with the following password: Demo_password1! (edit the variables OPAL_DEMO_USER_NAME and OPAL_DEMO_USER_PASSWORD accordingly). Here, we will open a connection to our local server using these credentials:

# define global variables
USERNAME <- "demo_user"
USERPASS <- "Demo_password1!"
PROJECT <- "DEMO"
TABLES <- c("CNSIM1")
SERVER <- "https://opal-demo.obiba.org"
PROFILE <- "demo"

Test deployment

  1. On a web browser, navigate to http://localhost:8880 and use the credentials on the docker-compose.yml to log in (e.g., administrator and password).

  2. Inside RStudio (or your preferred IDE), you can test the connection to the local server with the following command (note that you might need to update the username and password):

    opalr::opal.login( 
    username = "administrator", 
    password = "password", 
    url = "https://localhost:8843/" 
)

    You should see something like the following: bash url: https://localhost:8843 name: localhost version: 5.2.0 username: administrator

  3. (Optional) Next, you can attempt running some commands with {dsBaseClient}:

     # for setup only 
 DSOpal::Opal() 
 # create new login object 
 builder <- DSI::newDSLoginBuilder() 
 builder$append(server = "study1", 
                url = "https://localhost:8843/", 
                user = "administrator", 
                password = "password", 
                driver = "OpalDriver") 
 logindata <- builder$build() 
 conns <- DSI::datashield.login(logins = logindata) 

 # assign table to symbol, `test` 
 DSI::datashield.assign.table(conns["study1"],  
                              symbol = "test", 
                              table = "DEMO.CNSIM1", 
                              errors.print = TRUE) 

 dsBaseClient::ds.ls(datasources = conns["study1"]) 
 dsBaseClient::ds.summary("test")