i2b2/tranSMART beta-18.1 Quick-Start Guide

Note: database is pre-populated with the NHANES public dataset.

1) Download from Github

Git clone from the repository at https://github.com/hms-dbmi/docker-images

-- Docker Host Hardware Requirements

• 8GB RAM
• 128GB Hard Drive
• Docker for Mac and Docker for Windows are not supported
  • Instead, see https://tinyurl.com/docker-VM

-- Docker Network Requirements

• HTTP (80) and HTTPS (443) ports (default)
• Edit .env file to assign different ports

HTTP_PORT=
HTTPS_PORT=

-- Compatible Docker Versions

Docker: 17.06.2+
docker-compose: 1.14.0+

2) Install docker-ce

On Ubuntu 16.04, systems docker (if installed) is an old version. Follow the instructions at https://docs.docker.com/install/linux/docker-ce/ubuntu/ to set up the docker-ce repository and to install.

You can use sudo, or add your user to the docker group.

3) Install docker-compose

On Ubuntu 16.04 systems, the installed version of docker-compose is too old. Install a more recent version (check for the current version) with:

sudo curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-`uname -s`-`uname -m` \
                 -o /usr/local/bin/docker-compose

Next, we'll set the permissions:

sudo chmod +x /usr/local/bin/docker-compose

Then, we'll verify that the installation was successful by checking the version:

docker-compose --version

-- Current Service Versions

nginx:          i2b2tm.release-18.1
i2b2transmart:  release-18.1-beta-5
database:       oracle.12.2.0.1-ee-i2b2.1.7.09-tm.release-18.1-v.1.3-nhanes
rserve:         3.2.1-tm.release-18.1
solr:           4.5.0-tm.release-18.1
i2b2-wildfly:   1.7.09c-18.1-beta-hotfix
fractalis:      0.4.2
irct:           1.4.2
irct database:  mysql.5.7.22-irct.1.4.2-i2b2-nhanes

4) Deploy

$ cd deployments/i2b2transmart/quickstart

# images take several minutes to download
$ docker-compose pull

# NOTE: if you are running docker-compose version 1.21.0+
# and the pull command fails, try:
# $ docker-compose pull --no-parallel

# deploy database *first deploy only*
# database may hang here for a few minutes
$ export COMPOSE_HTTP_TIMEOUT=300
$ docker-compose up -d db

# verify database is up and running *first deploy only*
$ docker-compose logs -f db
# db_1            |#########################
# db_1            | DATABASE IS READY TO USE!
# db_1            | #########################

# deploy i2b2/tranSMART + fractalis
$ docker-compose up -d

5) Test i2b2/tranSMART beta-18.1

1. Browse to your docker machine IP http://localhost:80/transmart
2. i2b2/tranSMART, by default, uses self-signed certificates. If the browser complains about security, 'click OK' to allow for security exception.
3. Default username and passwords are used, e.g. admin/admin

6) Troubleshoot

The biggest point of failure is deploying the database for the first time. Due to its size and resource requirements, your Docker client may timeout during first deployment of the database.

Docker is transferring the data from the Docker database image to the named volume quickstart_i2b2transmart-db. Notice, by running docker system df the total volume size increase:

TYPE          TOTAL         ACTIVE        SIZE          RECLAIMABLE
Local Volumes 11            2             25.24GB       25.24GB (100%)

If you run into a timeout error...

ERROR: for quickstart_db_1  HTTPSConnectionPool(host='xxxx', port=2376): Read timed out. (read timeout=60)

...wait for data transfer to complete and the client to re-sync with the docker machine (~100s). Resume the deployment by running docker-compose up -d db again.