Installing the Virtual Servers

Install VirtualBox

To run the virtual servers you will need to install VirtualBox.

On Ubuntu:

$ sudo apt-get install virtualbox

Download the Virtual Servers

Two virtual servers are available for you to test DataSHIELD with. The virtual servers require 4GB RAM each and about 5GB hard-disk space each.
You can download the VMs from google drive:

Import the Virtual Servers into VirtualBox

You will need to import the VMs into Virtualbox. Open Virtualbox:

File > Import Appliance

Setting up the Virtual Servers

Setting up the VirtualBox network adapter

• On the VirtualBox top menu go to the tab File and select Preferences... , this opens up a VirtualBox settings window.
• Inside that window and under the tab Network click on Host-only Networks  and then click on the screw driver icon on the right which says Edit host-only network (Space) when you hover on it.

• Under the Adapter tab the following should be set:
  IPv4 address: 192.168.56.1
  IPv4 Network Mask: 255.255.255.0

• Under DHCP Server tab make sure that Enable server is unchecked. Select OK to save the settings.

Snapshot the Opal Servers

Before starting the Opal servers it is very useful to take a snapshot. This enables you to roll-back the Opal servers to a pristine state, without needing to delete them and repeat the process above to re-import them.

To take a snapshot, first open VirtualBox and click on a server. Now click the button in the top right that says Snapshots , the camera icon (for VirtualBox 6, click on a server, click the three horizontal lines to open a menu and select 'Snapshots', then click the 'Take' button).

Remember you must repeat this for each Opal server

Connect to the Virtual Servers

Starting the Opal test servers

See Start the Opal Servers

VirtualBox Networking

• The host machine and the virtual servers are able to communicate with each other through a host-only network. This network cannot communicate with any other network your (host) computer might be on. The host-only adapter will be configured when you import the Virtual Servers, no extra setup is necessary.

• The virtual servers also have a second 'NAT' network adapter. This does enable them to communicate through a network the host computer might be on. Consequently you will be able to update the servers (e.g. sudo apt-get upgrade) or install R packages from CRAN or github.

Virtual Servers' IP addresses

By default, machines on the host-only network can be found at 192.168.56.xxx:

Your computer (the host) will be at 192.168.56.1
The virtual servers have been configured as follows:

• dstesting-100 – 192.168.56.100
• dstesting-101 – 192.168.56.101

Opal web access

You can use the opal web interface in you browser. Simply type the ip address of the VM, followed by the port number.

For example: to access the web interface for dstesting-100, go to:

• http://192.168.56.100:8080
• https://192.168.56.100:8443

username: administrator
password: datashield_test&

SSH access

Once the machines have been started you can login directly, or you have ssh access:

Username: user
password: password

or

Username: root
password: puppet

For example:

$ ssh user@192.168.56.100

Note: you may want to alias the virtual servers in the host's ~/.ssh/config by adding the following:

$ cat >> ~/.ssh/config << 'EOF'
Host        server0
HostName    192.168.56.100
User        user
EOF

Now you can ssh into the virtual server by:

$ ssh server0

Shutting down the Opal servers

See Shutting down the Opal Servers for instructions on how to shut down the servers depending on whether you have or have not made changes to the Opal test servers.

Setting up your local machine to use the VMs

Installing R in Ubuntu

Do the following as root:

$ sudo su

Add a CRAN R repository

Add the following to /etc/apt/sources.list, this gives a newer version of R than the one that is in Ubuntu's repositories:

deb https://cloud.r-project.org/bin/linux/ubuntu xenial-cran35/

You may wish to select a different CRAN mirror, closer to your location.

You can find further details about installing R in Ubuntu on the CRAN website.

Add the public key for the CRAN R repository to your list of keys

# apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9

Install R

(Plus one dependency, needed for installing R packages)

# apt-get update
# apt-get install r-base r-base-dev libcurl4-openssl-dev

# apt-get install libxml2-utils
# apt-get install libxml2-dev
# apt-get install libssl-dev
# apt-get install libgit2-dev

Set-up R for DataSHIELD analysis

Don't do this as root.

Install the Opal packages

$ R
install.packages('rjson')
install.packages('RCurl')
install.packages('mime')
install.packages('opal', repos='http://cran.obiba.org', type='source')
install.packages('opaladmin', repos='http://cran.obiba.org', type='source')

Install the DataSHIELD client packages

install.packages('dsBaseClient', repos=c(getOption('repos'), 'http://cran.obiba.org'), dependencies=TRUE)

DataSHIELD R Package Manuals

See: Current release

Keeping up to date

If you have installed the DataSHIELD client packages using the method above (that is, within R using install.packages and specifying the Obiba repository), then you can update those client packages as follows:

# R
update.packages(repos='http://cran.obiba.org')