Building a REDCap Environment

These instructions describe how to set up a development environment that works on both Mac OSX, Windows, and Linux computers. While this version presents some issues for Windows computers, future versions should address that shortcoming through the use of git-bash.

Setup Checklist for New Developers

This is a short list to get started, links to the required software are presented in the next section

Create a GitHub account
If using Windows, install git-bash
Install GitHub desktop
Configure GitHub desktop for your GitHub account
Install your editor
Configure GitHub desktop to use your editor, and git-bash
Install Docker Desktop
Download and unzip redcap-docker-compose
Set up your REDCap development instance

Required Resources

These tools are recommended for those with no experience in software development, if you already know what you're doing, feel free to substitute your preferred tool where applicable (e.g. a different editor).

A computer on which you have admin rights
Windows users will need to install git bash - https://gitforwindows.org/
A suitable web browser with developer tools Firefox or Chrome.
- Firefox dev tools documentation
- Chrome dev tools documentation
GitHub account - https://github.com/
GitHub Desktop - https://desktop.github.com/
Docker Desktop - https://www.docker.com/products/docker-desktop
Text editor or PHP IDE - VSCode/VSCodium or PHPStorm, may be best for beginners.
redcap-docker-compose - A docker environment tailored for running and developing for REDCap. See https://github.com/123andy/redcap-docker-compose
A REDCap .zip file - Ask your local REDCap Admin for a recent REDCap Zip file downloaded from the REDCap Community. The REDCap Zip files have names like redcap10.3.3.zip where '10.3.3' is the REDCap version number. If you are that REDCap Admin and have access to the community, the download link is https://community.projectredcap.org/page/download.html. Please be generous with access to the resources your employees and customers need to learn and develop for REDCap while reminding them of the need to not redistribute REDCap software outside the entity that has licensed it.

REDCap-Specific Setup

Open the redcap-docker-compose directory in your editor

VSCodium open folder VSCodium select redcap-docker-compose folder

Open the file .env in the rdc directory (note that in Windows you can not simply double click the .env file to open it)

VSCodium select .env file

Paste this block at the end of the file and save it. Make changes to reflect your timezone and REDCap version number. You can find a list of valid time zones at List of tz database time zones
The port numbers should reflect your REDCap version number in some way so you can keep your different REDCap installations from colliding and tell them apart. Each of these port numbers needs to be unique. The standard used here compresses the REDCap version number into 4 digits and prefixes it with 1 through 4. For example, 10.3.3 becomes 1033. With prefixes, that becomes 11033, 21033, 31033, and 41033. Any method that makes unique port numbers and works for you is fine, though be aware that the max allowed port number is 65535.

TZ=America/Chicago
DOCKER_PREFIX=redcap
WEB_PORT=11033
MYSQL_PORT=21033
PHPMYADMIN_PORT=31033
MAILHOG_PORT=41033

You'll need a terminal that's in the redcap-docker-compose directory to start the Docker containers

If you used VSCode or another IDE with an integrated terminal for the previous steps, you already have a terminal attached and in the desired directory
If you did not use VSCode, open a terminal or git-bash session and cd to the redcap-docker-compose directory
- GitHub Desktop can open a terminal cd'd to the redcap-docker-compose folder with the shortcut <ctrl>`
Change directories into the rdc folder with the command cd rdc
In the terminal start the containers with this command docker-compose up -d

terminal nav and docker-compose up -d

Your Docker containers are now downloading required software and initializing. This step will take some time, especially on the first run.

Once the containers are built, wait one more minute for the webpage to finish setting up.
Access web-based redcap installer at http://localhost:1935 You should see this:

REDCap Docker-Compose Installer

Select 'Use a local copy of the full zip installer...'. Click Browse, locate your redcap zip file (e.g. redcap10.3.3.zip), and upload it.
Select 'Prepopulate with table-based users and activate table authentication' and provide your email address.
Click 'INSTALL REDCAP'
Wait a couple of minutes.
When you see the green dialog boxes, the installation is complete.

Successful installation

Ignore the website instructions to access the REDCap installer and access your fully functional local REDCap at http://localhost:1935
Login as admin. Your password is 'password'. Every user's account is 'password'.

It didn't work!

Sometimes things are weird, and you'll have to rebuild from scratch. To do that, you'll need to open a terminal to the redcap-docker-compose folder and issue these commands:

# Preserve your modules folder because it might have stuff worth preserving
cp -r www/modules .

# The installer will get confused if any part of your old installation exists
rm -rf www
rm -rf logs

# You have to be in the right folder for docker-compose to find its config files
cd rdc

# Destroy the containers and their volumes
docker-compose down -v

# Rebuild the containers and volumes from scratch
docker-compose up -d

If it fails again, you'll need to dig deeper to find out why. It's probably just a small thing, but knowing which small thing is hard to anticipate. Sorry about that.

After setup

Now that you have a working local instance of REDCap, you'll want to get familiar with the tools available to a REDCap administrator in EMD-102: A Tour Through REDCap as an Admin before moving on to the training exercises in REDCap External Module Development for Developers.

Add an extension to VS Code

VSCode can show you syntax errors as you type them if you add an extension. Add the PHP Intellisense extension to VS Code to get this functionality. On Mac access Code > Preferences > Extensions and type "PHP". You'll see PHP Intellisense in the list. Install it.

Open some PHP code, delete a semicolon or a comma and watch for the wiggly red lines under the text. Hover on one next to the text you just changed and consider what the editor is telling you.

Footnotes

These instructions were adapted from a REDCap Development Class presented at the University of Arkansas Medical School in February 2020. The original document is located here.