---
title: "Deploy a local DataSHIELD server with Opal"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Deploy a local DataSHIELD server with Opal}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  cache = FALSE
)
```


```{r}
#| echo: false
#| label: setup
library(dsROCrate)
```

### What is Opal?

> Opal is [OBiBa](https://www.obiba.org/)’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](https://www.maelstrom-research.org/) 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](https://datashield.org/) infrastructure. More information on Opal can be found in the [Opal description on OBiBa](https://www.obiba.org/pages/products/opal/).

**Source:** [https://isglobal-brge.github.io/resource_bookdown/opal.html](https://isglobal-brge.github.io/resource_bookdown/opal.html)

### Deploy Docker containers
Here we will spawn a local instance of [DataSHIELD](https://datashield.org) with 
[Docker](https://www.docker.com). 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](https://www.docker.com/get-started/) page.

#### Setup
The easiest way to deploy DataSHIELD with docker is by cloning the following
repo: [FederatedMethods/datashield_dev_install](https://github.com/FederatedMethods/datashield_dev_install).
Here, you will find a step by step guide, including a very useful
[`docker-compose.yml`](https://github.com/FederatedMethods/datashield_dev_install/blob/main/docker/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:

```sh
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:

<img src="../man/figures/ds_docker_compose.png" alt="Docker conf" height=200px/>


---------

#### Open connection

By default, the [`docker-compose.yml`](https://github.com/FederatedMethods/datashield_dev_install/blob/main/docker/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:

```{r}
# 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` <!-- @URLok --> 
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`): 
 
     ```r
     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}`:
 
    ```r
     # 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")
    ```