dzdde/redcap-docker repository overview

⁠redcap-docker

Yet another try to containerize REDCap⁠ — but with a focus on automated, hands-off deployments.

Status: Usable - beta
Maintainer: Tim Bleimehl, DZD
Docker image: dzdde/redcap-docker⁠
Source: github.com/DZD-eV-Diabetes-Research/redcap-docker⁠

https://github.com/DZD-eV-Diabetes-Research/redcap-docker/issues⁠)

• redcap-docker⁠
  • Disclaimer⁠
  • About & Motivation⁠
  • Features⁠
  • Security⁠
  • Quick Start⁠
    • Option A — Auto-install via community portal⁠
    • Option B — Mount your own REDCap files⁠
  • Container Reference⁠
    • Environment Variables⁠
      • REDCap application settings⁠
      • Email⁠
      • Cron mode⁠
    • Volumes & Paths⁠
      • REDCap file repository⁠
    • User Provisioning⁠
    • Module Provisioning⁠
    • File Ownership⁠
  • Updates & Upgrades⁠
  • Beta Channel⁠
  • Contributing & Development⁠
  • Example Setups⁠
  • Roadmap⁠

⁠Disclaimer

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 simple 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, or a valid login to the REDCap community portal to download it.

⁠About & Motivation

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.

Target audience

• 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.

⁠Features

• Auto-install/upgrade/update Set REDCAP_VERSION and your community portal credentials and the container downloads and installs REDCap on first boot, no manual file copying required
• Manual upgrade/update-wizard (redcap-upgrade) 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 Updates & Upgrades⁠.
• Security-hardened by default — read-only webroot, HTTP security headers, PHP hardening, Docker Secrets support. REDCap's browser-based Easy Upgrade is disabled by default (see Security⁠).
• Automated testing We run an automated testing rig, to validate security and functionality before every change and/or release (see Testing⁠).
• External Module Provisioning install/enable modules from GitHub, a zip URL, a mounted dir, or the REDCap central repo, all via environment variables and/or YAML files. see Module Provisioning⁠
• Database and application configuration entirely via environment variables
• Automated DB schema installation . No need to manually run install SQL scripts
• 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

⁠Security

The container ships with several hardening defaults:

• Read-only webroot — the www-data process cannot write PHP files into the webroot, closing off the main vector for persistent backdoor injection. REDCap's built-in browser-based upgrade ("Easy Upgrade") is disabled by default for this reason. The container's own redcap-upgrade command and REDCAP_AUTO_UPGRADE are unaffected and remain the recommended upgrade path. For the same reason, REDCap's web UI external-module installer (Repo download / ZIP upload) does not work under the hardened webroot — use Module Provisioning⁠ instead (or set REDCAP_EASY_UPGRADE_ENABLE=true to re-enable the web UI, not recommended for production).
• HTTP security headers — X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy — sent on every response.
• PHP hardening — expose_php = Off, display_errors = Off.
• Docker Secrets support — sensitive variables (DB_PASSWORD, DB_SALT, REDCAP_COMMUNITY_PASSWORD) can be loaded from files via _FILE variants to avoid plaintext env vars.
• File integrity checker — redcap-integrity-check compares the running installation against a canonical download to detect injected or modified PHP files.

Full details, configuration options, and production hardening guidance: SECURITY.md⁠

⁠Quick Start

There are two ways to get REDCap files into the container. Choose the one that fits your setup.

⁠Option A — Auto-install via community portal

The recommended path for new deployments. The container downloads REDCap directly from the community portal on first boot.

Requirements: a valid REDCap community portal account.

# docker-compose.yaml
services:
  redcap:
    image: dzdde/redcap-docker
    environment:
      # --- REDCap source ---
      REDCAP_VERSION: "14.9.5"
      REDCAP_COMMUNITY_USER: your_community_username
      REDCAP_COMMUNITY_PASSWORD: your_community_password

      # --- Database ---
      DB_HOSTNAME: db
      DB_NAME: redcap
      DB_USERNAME: redcap
      DB_PASSWORD: redcap123
      DB_SALT: changeme_use_a_random_string

      # --- REDCap base URL ---
      RCCONF_redcap_base_url: "http://localhost"
    volumes:
      - ./data/redcap:/var/www/html   # REDCap files persist here
      - ./data/backups:/opt/redcap-docker/backups
    ports:
      - "80:80"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mysql:lts
    environment:
      MYSQL_DATABASE: redcap
      MYSQL_USER: redcap
      MYSQL_PASSWORD: redcap123
      MYSQL_ROOT_PASSWORD: redcaproot123
    volumes:
      - ./data/db:/var/lib/mysql
    healthcheck:
      test: "/usr/bin/mysql -u $$MYSQL_USER -p$$MYSQL_PASSWORD $$MYSQL_DATABASE -e 'SHOW TABLES;'"
      interval: 5s
      timeout: 3s
      retries: 5

docker compose pull             # pull the latest image — we ship fixes frequently
docker compose up -d
docker compose logs -f redcap   # watch the install progress

On first boot the container downloads the REDCap zip, extracts it, and runs the install SQL. Subsequent boots skip the download — the files are already on the volume.

⁠Option B — Mount your own REDCap files

If you prefer to manage the REDCap source yourself, mount it at the document root. No community portal credentials are needed.

services:
  redcap:
    image: dzdde/redcap-docker
    environment:
      DB_HOSTNAME: db
      DB_NAME: redcap
      DB_USERNAME: redcap
      DB_PASSWORD: redcap123
      DB_SALT: changeme_use_a_random_string
      RCCONF_redcap_base_url: "http://localhost"
    volumes:
      - ./data/redcap:/var/www/html   # must contain redcap_vX.X.X/ directory
    ports:
      - "80:80"

Place your REDCap source (the redcap_vX.X.X/ directory) inside ./data/redcap/ before starting the container.

See the minimal example⁠ for a complete working compose file.

⁠Container Reference

⁠Environment Variables

See config_vars_list.md⁠ for the full variable reference.

⁠REDCap application settings

Any key from the redcap_config database table can be set at startup by prefixing it with RCCONF_:

RCCONF_auth_meth_global=table
RCCONF_redcap_base_url=https://redcap.example.com
RCCONF_institution=My Institution

See config_vars_list.md — REDCap Application Config vars⁠ for the full list.

⁠Email

Mail is sent via msmtp. Prefix any msmtp config directive with MSMTP_:

MSMTP_host=mail.example.com
MSMTP_port=587
MSMTP_auth=on
[email protected]
MSMTP_password=secret
MSMTP_tls=on
MSMTP_tls_starttls=on
[email protected]

See config_vars_list.md — MSMTP⁠ for all options.

⁠Cron mode

Run the REDCap cron process in a separate container using the same image:

services:
  redcap-cron:
    image: dzdde/redcap-docker
    environment:
      CRON_MODE: "true"
      CRON_INTERVAL: "*/5 * * * *"
      # same DB_* and REDCAP_* vars as the web container

See the cron example⁠ for a full setup.

⁠Volumes & Paths

⁠REDCap file repository

By default user-uploaded files live inside the document root at /var/www/html/edocs. To move them outside the web root (recommended):

RCCONF_edoc_path=/data

And add a volume mount for /data. See the custom edocs example⁠.

⁠User Provisioning

Pre-populate REDCap with table-based users on container boot, via environment variables or YAML/JSON files.

• Full documentation: USER_PROV.md⁠
• Working example: docker compose example⁠

# Simplest form — inline JSON
USER_PROV='[{"username":"admin","user_firstname":"Admin","user_lastname":"User","user_email":"[email protected]","password":"secret","super_user":1}]'

⁠Module Provisioning

Install (and optionally enable + configure) REDCap external modules on container boot, via environment variables or YAML/JSON files. Sources: a GitHub release, an arbitrary zip URL, a pre-mounted directory, or the REDCap central repository.

• Full documentation: MODULE_PROV.md⁠
• Working example: docker compose example⁠

ENABLE_MODULE_PROV=true
# Default is install-only; set true to system-enable provisioned modules.
MODULE_PROV_DEFAULT_ENABLE=false
MODULE_PROV_1='{"source":"github","repo":"vanderbilt-redcap/redcap-banner","version":"1.2.0","enabled":true}'

⁠File Ownership

By default the Apache process runs as www-data (UID/GID 33/33). Override with:

WWW_DATA_UID=1000
WWW_DATA_GID=1000

⁠Updates & Upgrades

See REDCAP_UPGRADE.md⁠ for complete documentation.

Quick reference:

# Interactive upgrade wizard
docker compose exec -it redcap redcap-upgrade

# Interactive install wizard (first boot, no REDCAP_VERSION set)
docker compose exec -it redcap redcap-install

⁠Beta Channel

Some features are released as beta before they land in the stable image. To try them, use the beta tag:

services:
  redcap:
    image: dzdde/redcap-docker:beta

Beta images are published automatically when a pre-release is created on GitHub. They may contain bugs — please report issues⁠.

⁠Contributing & Development

See DEV_README.md⁠ for the project structure, where to add new features, and how to run the integration tests.

⁠Example Setups

If you are more of a hands-on learner; Under examples/README.md⁠ you can find examplary setups with some documentation.

⁠Roadmap

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.