# 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:

#### 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")