Skip to main content

Set Up Instructions for Docker on Ubuntu

Original Author: Sumon C, December 6, 2021

Overview​

Below are instructions to install and configure a running REDCap server on your local Ubuntu machine. By the end of this guide, you will have your own personal copy of REDCap, independent from the institutional copy, that can be used for development and testing of external modules and other REDCap related software.

If you have a Windows machine, you can skip to the next section.

These instructions assume you have super user level access on your machine.

Install Docker​

Docker has official documentation for installing Docker Engine onto your Ubuntu machine, as they do not have Docker Desktop for Linux available for the public.

At REDCap@Yale, we follow the recommended approach and use the repository method to install Docker Engine.

To prevent discrepancies between our instructions and Docker's official documentation, we simply link to the instructions here. Follow the instructions on the official Docker documentation, until the section titled "Update Docker Engine".

Download the Yale REDCap Docker image​

note

Yale REDCap-Docker-Compose is referred to as "RDC".

You can choose any directory to download and install your Yale REDCap Docker image. For convenience, we will use the ~/Containers directory in our example.

Create the Container directory in your home directory:

cd
mkdir Container
note

From here this location is noted as: ~/Containers.

Next, obtain a copy of the "Yale-REDCap-Docker-Main" i.e. RDC (Currently on REDCap@Yale network drive)

Then, copy the RDC folder to ~/Containers/yale-redcap-docker-main.

Run the Yale REDCap Docker Image​

Once the RDC is copied into the directory, you are ready to run your own copy of REDCap.

In your terminal, change directories to the rdc directory:

cd ~/Containers/yale-redcap-docker-main/rdc

Then start the REDCap containers with the following command:

docker-compose up -d
note

The -d option instructs Docker to run in the background

Wait until the containers are finished building.

Finishing the Docker Build from a web browser​

Once all the containers are up and running, open a web browser and navigate to http://localhost:8081.

note

Instead of 8081, you may use whatever port you specified in the .env file located within RDC.

You should now see a page titled: "REDCap-Docker-Compose Installer".

There will be two options here for installing REDCap:

  1. "Use your Community Consortium login"
    • This will use your credentials to download an installer from the REDCap Consortium site.
  2. "Use a local copy of the full zip installer".
    • This may be the quickest and easiest option.
note

The REDCap_install.zip can be found on the REDCap@Yale network drive.

Once the install is complete, use a web browser to navigate to http://localhost:8081 to log into REDCap.

note

If you selected the option to "Prepopulate with table-based users...", the user passwords will be "password".

You should now have a running REDCap instance on your Ubuntu machine!

EM development​

To have external modules appear in your REDCap, the files and folders required for the external module must reside within the modules directory in the www directory created by the RDC installation steps.

We recommend you directory work within this directory so that changes are immediately reflected. You can directly park your external module's Git repository containing code within the modules directory.

You will need to append suffix _v0.0.0 to the directory name for the external module to appear within the REDCap Control Center. This also circumvents the need to increment the version of your external module for minute changes.

Bibliography​

The above instructions have been heavily adapted from these following resources:

More in depth instructions have been adapted from here: https://github.com/123andy/redcap-docker-compose/blob/master/rdc/documentation/README.md#configuration

If you are curious or have any questions, we recommend you read these resources.