Yet another try to containerize REDCap — but with a focus on automated, hands-off deployments.
Status: Work in progress · beta
Maintainer: Tim Bleimehl, DZD
Docker image: dzdde/redcap-docker
Source: github.com/DZD-eV-Diabetes-Research/redcap-docker
- redcap-docker
This is not an official REDCap project. We are an institutional partner of the REDCap Consortium, but beyond that we have no connection to REDCap — we are simply REDCap users.
This project does not distribute REDCap and never will. It is a wrapper to help deploy REDCap. You still need to provide your own licensed copy of REDCap.
Caution
We are not responsible for any data loss or damage that may occur from the use of this container image. Use it at your own risk. Make backups.
Our infrastructure emphasises automation and reproducibility through containerization. While excellent solutions like Andy's redcap-docker-compose exist and were a great help when building this repo, we could not adapt them to our environment without manual intervention during setup.
This project is our attempt to containerize REDCap in a way that allows deploying a fresh instance with zero manual steps.
- IT Operators — professionals with container operations knowledge who need to deploy and manage REDCap instances.
- REDCap Admins — users familiar with Docker or Podman who need local REDCap instances for testing or experimentation.
- Automated installation — no need to manually copy or run REDCap-generated SQL scripts
- Database and application configuration via environment variables
- Simple mail setup via environment variables (
msmtprc-based) - Automated routine tasks such as deactivating the default admin (optional)
- "Cron mode": run the same image as the REDCap cron job manager
- User provisioning via environment variables and/or YAML files
- 🧪 [BETA] Built-in server-side upgrader (
redcap-upgrade) as a replacement for the deprecated Easy Upgrade. It checks for updates, downloads from the REDCap community portal, runs SQL migrations, creates a database backup, and rolls back. All from a single command inside the running container. See REDCap Updates & Upgrades.
This guide assumes basic familiarity with
dockeranddocker composeand that both are installed.
Important
Batteries not included. Due to REDCap's licensing, you must provide the REDCap source code (PHP scripts) yourself.
See the minimal docker compose example for a working starting point you can bring up right away.
See config_vars_list.md for the full list of available variables.
REDCap application settings can be configured via environment variables. Prefix any key from the redcap_config database table with RCCONF_ to set it at startup.
Example: RCCONF_auth_meth_global=table
See REDCap application env vars for a list of available options.
See config_vars_list.md — msmtp for all mail-related variables.
You can use the same Docker image to run the REDCap cron process. Set the environment variable CRON_MODE=true.
Note: You still need a separate container running the REDCap web server.
- See config_vars_list.md — cron for all cron-related variables.
- See the cron example compose for a full setup alongside a REDCap web instance.
The REDCap PHP scripts must be placed in:
/var/www/html
This path can be changed via the APACHE_DOCUMENT_ROOT environment variable.
Drop any .ini files into this directory to extend the PHP configuration. See the PHP ini reference for all available settings.
/config/php/custom_inis
Configurable via the PHP_INI_SCAN_DIR environment variable.
/config/apache/custom.virtualhost
You can supply the REDCap installation SQL script generated by http(s)://<yourredcapdomain>/install.php:
/config/redcap/install/install.sql
If this file exists and the redcap_config table is not yet present in the database, the script will be executed at startup. If no file is provided, a generic version is derived from the REDCap sources you supply.
Configurable via the REDCAP_INSTALL_SQL_SCRIPT_PATH environment variable.
/opt/redcap-docker/users
This directory is scanned for user data to provision at startup. See User Provisioning for details.
By default, user-uploaded files are stored in the document root at /var/www/html/edocs. As recommended by the REDCap documentation, you may want to move this outside the web root.
Set RCCONF_edoc_path to any path of your choice (e.g. RCCONF_edoc_path=/data) and mount that path into the container.
See the custom edocs compose example for a working setup.
The container can pre-populate your REDCap instance with table-based users. The simplest way is to supply user data via the USER_PROV environment variable as JSON, but file-based provisioning is also supported.
- Full documentation: USER_PROV.md
- Environment variable reference: config_vars_list.md — user provisioning
- Working example: docker compose example
Important
When using user provisioning you will almost certainly also want to set the authentication method to table:
RCCONF_auth_meth_global=table
If the default UID/GID of the container's internal Apache user does not suit your environment, see WWW_DATA_UID / WWW_DATA_GID for how to override it.
Some features are released as beta before they land in a stable image. To try them, use the beta tag instead of latest:
# docker-compose.yaml
services:
redcap:
image: dzdde/redcap-docker:betaBeta images are published automatically when a pre-release is created on GitHub. They may contain bugs — please report issues if you find any.
🧪 BETA — The container ships a built-in upgrade command. Run it without arguments for an interactive wizard, or pass
--version X.X.Xfor scripted upgrades.
docker compose exec -it redcap redcap-upgradeSee REDCAP_UPGRADE.md for full documentation, including manual fallback procedures.
Planned
- Update user admin privileges for existing users (including external users via LDAP or OAuth2)
Ideas under consideration
- Project provisioning
- Automated data exports
Feedback and contributions are welcome — open an issue to start the conversation.