DataSHIELD install environment
We need docker-ce, docker-ce-cli, docker-compose-plugin, plus their prerequisites.
Follow the instructions here: https://docs.docker.com/engine/install/ubuntu/ to add the apt install.
You can verify docker is set up by running:
sudo docker run hello-world
It's all done via the docker compose file, so just run sudo docker compose up -d from within the folder with the docker-compose.yml file in and you should be good to go. You will want to edit a couple of things first though:
- the opal volume should map to somewhere on your host machine. Something like
/filestore/opal:/srvwill map the/filestore/opalfolder on the host to the/srvfolder in the container. This is where the opal file data will be stored e.g. logs. - there are vaious usernames and passwords in here which should be managed properly elsewhere.
- the csr-allowed setting is needed as it sometimes appears that cross site scripting is occuring when pages are passing through the reverse proxy. Specify expected
host:portpairs here.
This will get you to the point where it is all running locally, you will be able to connect to the opal server web interface (assuming you are on the VM where it was installed) at
http://localhost:8880
https://localhost:8843
If you installed this on a remote host then you will likely need to add a reverse proxy to the front with a valid SSL certificate.
sudo apt install nginx
This should start nginx also. If you go to the hostname or IP address of the HOST VM from outside of the VM it should show a welcome to nginx landing page.
For development a self signed certificate is fine. A good guide for this is here:
Once you have done this, create a file in /etc/nginx/sites-available and put the contents of nginx/datashield1 into it. You will need to edit the hostname to match the fqdn of your host VM, or use its IP address. Softlink to it :
sudo ln -s /etc/nginx/sites-available/datashield1 /etc/nginx/sites-enabled/datashield1
Remove the default enabled config:
sudo rm /etc/nginx/sites-enabled/default
Test your config and reload nginx
sudo nginx -t
sudo systemctl reload nginx
You should now be able to log into the opal web interface from outside of the host VM (username/password in docker-compose.yml file). If you have used a self signed certificate as above then you will likely get a warning about the site being insecure (your browswer can't validate the certificate as it was not generated by someone that it knows it can trust). Just accept this for this test/dev work.
If using Uncomplicated Firewall (UFW) on the host machine, you will need to allow the appropriate ports. For example:
sudo ufw status
sudo ufw app list
sudo ufw allow 'Nginx HTTPS'
When developing, it is useful to be able to delete everything and start over.
sudo docker compose down
sudo rm -r <PATH TO OPAL DATA ON THE HOST>
sudo docker compose up -d
Occasionally when doing development a container may get STOPPED (e.g. if run docker compose up then CTRL-C in browser). When running docker compose up after this the stopped containers will be RESTARTED, not made fresh from the image. If you've deleted stuff this can lead to inconsistencies. It's good to check
sudo docker ps -a
to check if old containers hanging around, and
sudo docker system prune
to tidy up.
Sometimes is useful to be able to log into the opal server and check the logs. This can be done with the following command:
sudo docker exec -it <container ID> bash
Once everything is up and running server side the next test to see if you can connect to the server from the client side. There is an example script in the client folder which can be run from the client side. This will connect to the server and run a simple test. You will need to install the dsBaseClient package. This can be done with the following command:
install.packages("dsBaseClient", repos = "https://cran.obiba.org")
- Could add a reverse proxy to the docker-compose file. How to manage the SSL certificate though?
- I can't get group permission to work properly. Having to add individual users.