Tutorial: Cómo obtener, instalar y hacer la configuración inicial de REDCap

jdeloshoyos Jaime de los Hoyos M.
9 Abril Hola a todos,
Hemos visto bastante interés de la comunidad en relación al reciente post de Alejandro, en que se pone a disposición de la comunidad un proyecto en REDCap para el seguimiento de pacientes con Covid-19 (Sistema de Seguimiento de pacientes Covid-19 GRATUITO, ESCALABLE y PERSONALIZABLE 2). Si bien tal vez varias de las instituciones que puedan estar interesadas en adoptarlo ya tengan una instancia de REDCap, seguramente habrá varias que no, y en ese sentido queremos dar un pequeño apoyo en forma de un tutorial en español, conciso y (espero) fácil de seguir y entender, para saber los pasos necesarios para la instalación y configuración en un servidor web de este gran software, para posteriormente importar el proyecto de seguimiento de Covid-19 (¡y crear muchísimos proyectos más!) como se indica en el post vinculado arriba. Antes de seguir, es necesario aclarar un par de puntos importantes:

• SE REQUIERE DE APOYO TÉCNICO PARA LA INSTALACIÓN Y CONFIGURACIÓN DE UNA PLATAFORMA WEB, por lo que contar con el apoyo del departamento o gerencia de TI de la institución donde se desea instalar REDCap es ABSOLUTAMENTE NECESARIO. Nosotros podemos dar en este tutorial estos punteros acerca de cómo se realiza una instalación típica de REDCap, pero operar un software que funciona sobre una plataforma web tiene muchas consideraciones importantes, entre ellas todos los aspectos relacionados con la seguridad. Por lo tanto, antes de seguir, ¡asegurarse de tener el apoyo y colaboración del área de tecnologías de información en nuestra institución!
• Relacionado con lo anterior, es importante ser muy enfático en que REDCap es un software que necesariamente funciona en un servidor. No es un programa que podamos cargar en nuestro computador personal (podríamos, pero no sería muy útil; sólo lo podríamos acceder nosotros mismos, salvo que queramos transformar nuestro equipo personal en un servidor… Lo que realmente no recomendamos por ningún motivo).

Sin más comentarios, entonces, pasamos a la acción:

1. El primer paso, y absolutamente necesario, es llevar a cabo la solicitud de incorporación al Consorcio REDCap. El software es gratuito para instituciones SIN FINES DE LUCRO, pero su descarga y uso no es libre; sus autores (Universidad de Vanderbilt) exigen que las instituciones interesadas se incorporen al consorcio; el proceso de solicitud de incorporación consiste en el llenado de un breve formulario disponible en su sitio web (que está implementado sobre REDCap, ¡así que ahí está la primera oportunidad de interactuar con el sistema mismo!). Las instrucciones para acceder al formulario, junto con otra información importante, está en este link 1.

Instrucciones de incorporación al Consorcio
Formulario de solicitud de incorporación

2. Una vez que tengamos la aprobación de nuestra solicitud, seremos parte del Consorcio REDCap y tendremos credenciales para bajar el paquete de instalación del software. Descargaremos la versión más reciente de REDCap (a la fecha de la escritura de este post es la versión 9.8.1). Además de esto, debemos descargar el paquete de lenguaje en español del mismo sitio (disponible en este link), que necesitaremos posterior a la instalación para dejar nuestro sitio REDCap en nuestro idioma.
3. Con lo anterior, ya tenemos los archivos que necesitaremos. Ahora tenemos que asegurar que nuestro servidor (el equipo en el cual instalaremos nuestra instancia de REDCap) esté preparado con todos los prerrequisitos necesarios. En particular, debemos asegurarnos que el servidor cuente con el siguiente software instalado y funcionando.

• Un software de servidor web (REDCap recomienda Apache o Microsoft IIS).
• PHP (Versión 5.3.0 o superior. PHP 7 está completamente soportado).
• Base de datos MySQL 5 o superior. Para la instalación será necesario poder acceder a la base de datos con un administrador como phpMyAdmin o MySQL Workbench (este último viene incluido con el instalador de MySQL para Windows, y se puede descargar por separado en el sitio web de MySQL). Nota: la versión gratuita de MySQL (MySQL Community) funciona perfectamente con REDCap.
• Un servidor de correo SMTP disponible para el envío de correos desde la plataforma REDCap. La casi totalidad de las instituciones que gestionan su propio correo cuenta con este tipo de servidor. El servidor SMTP no necesariamente debe estar corriendo en la misma máquina en que instalaremos REDCap.
• Requerimientos de espacio: la instalación misma de REDCap es relativamente liviana (cerca de 10 MB de almacenamiento para el servidor, y otros 10 MB para la base de datos inicialmente), pero se recomienda destinar al menos 10 GB para ambos componentes, servidor y base de datos. Bajo un escenario de uso típico, ese almacenamiento debería bastar para un año de uso y probablemente más también. De cualquier forma, mientras más espacio se pueda destinar, mejor.

4. ¡A instalar! Debemos iniciar por descomprimir el archivo .zip que descargamos en el paso 2, deberíamos obtener lo siguiente:

El contenido descomprimido del archivo descargado de REDCap debe contener dos archivos con instrucciones de instalación en inglés, y una carpeta llamada redcap. Ésta contiene los archivos que necesitaremos para la instalación. La carpeta “redcap” es la que contiene el sistema de software mismo. Debemos copiarla al directorio de nuestro servidor desde donde se ejecutará (para nuestro ejemplo, mantendremos el nombre “redcap” aunque podría ser distinto. Para esta copia, puede ser que tengamos que usar un software de FTP, como el excelente FileZilla para Windows, pero puede ser cualquier otro:
En el caso de mi servidor, la carpeta REDCap quedará como una subcarpeta llamada “redcap” en la raíz de mi servidor web. De esa manera, podré accederlo por medio de (mi.direccion.web/redcap). Con FileZilla, puedo simplemente arrastrarla desde el panel izquierdo (los archivos de mi computador local) a la carpeta public_html. Esta dirección puede variar según mi servidor web y su configuración, por lo que se debe trabajar con el apoyo de TI para esto. ¡Se debe preservar la estructura de directorios dentro de la carpeta “redcap” al copiarla al servidor! Asimismo, es importante señalar que la ruta de instalación puede ser la que yo prefiera; podría quedar, por ejemplo, como (mi.direccion.web/aplicaciones/formularios) o como prefiera realmente.

5. Una vez copiados los archivos, vamos a verificar que todo esté bien. Para esto, usaremos un navegador web como Chrome o Firefox, desde el cual tengamos acceso a nuestro servidor, y trataremos de abrir una página llamada “install.php” ubicada en el directorio donde instalamos REDCap. Por ejemplo, si como hice yo, instalamos REDCap en una carpeta llamada “redcap” ubicada en la raíz de mi servidor web, digitaremos lo siguiente en la barra de direcciones del navegador:

mi.direccion.web/redcap/install.php Ojo, que hemos usado “mi.direccion.web” como ejemplo. Nuestro servidor web estará expuesto en un dominio específico, debemos tener claro cuál es para acceder (de nuevo, apoyo del equipo TI  ) Si todo anda bien, debiéramos ver lo siguiente:
Si vemos esto, vamos bien encaminados

6. Ahora nos vamos a poner más técnicos. Necesitamos crear una base de datos, dentro de MySQL, para almacenar la información de nuestra instancia de REDCap. Para esto, debemos conectarnos a la base de datos y correr algunos comandos, que la página a la que llegamos en el paso anterior nos indica. Para conectarnos a la base de datos usaremos MySQL Workbench, en este caso:

Para crear la base de datos en MySQL usando MySQL Workbench, tras conectarnos a nuestra base de datos, debemos correr el script de creación de base de datos y usuario que nos mostró nuestra instalación de REDCap en el paso 5. Atención: en el script de creación de la página, hay instrucciones para MySQL y para MariaDB (otro sistema de base de datos, derivativo de MySQL). Para este tutorial, dado que estamos usando MySQL, quité las instrucciones que se referían a MariaDB. Observar también que cambié el password para el usuario de la base de datos (“passwordsupersecreto”  ). También podemos, si queremos, cambiar el nombre del usuario también (redcap_user) y de la base de datos misma. Es importante, en todo caso, que si hacemos eso, tomemos nota de los nombres que elegimos para ingresarlos en el paso siguiente. Una vez que tengamos el script editado como queremos, lo ejecutamos con el botón marcado en la imagen con “Ejecutar script”. Si funciona correctamente, veremos en la parte inferior del workbench mensajes similares a los indicados con “OK!” en la imagen.

7. A continuación, debemos configurar los parámetros de nuestra base de datos recién creada en la instalación de REDCap. Esto implica que editemos un archivo en el servidor, llamado “database.php” y que está ubicado en el mismo directorio en que instalamos el software. Si usamos FileZilla, podemos ubicar el archivo en el panel de la derecha y hacerle doble clic, con lo que lo editaremos en nuestro computador personal y, al guardarlo, FileZilla nos ofrecerá volver a subirlo con los cambios:

Estas son las líneas que debemos editar en el archivo “database.php”. Debe coincidir con los valores de nombre de base de datos, nombre de usuario, y password de usuario que creamos en el paso 6. Si el servidor de base de datos reside en la misma máquina que el servidor web, la variable hostname es “localhost”. Adicionalmente, debemos poner un texto en la variable “salt”, en la parte inferior de la imagen. Este texto debe ser aleatorio; puede ser inventado, consistente en letras y números. En la imagen es un ejemplo de una variable “salt”, pero se puede usar cualquier otra, de 8 caracteres o más. La importancia de esta variable es para la deidentificación posterior de registros.

8. Una vez que hayamos hecho los cambios en database.php y subido los mismos al servidor, vamos a verificar si REDCap puede comunicarse con la base de datos. Para esto, simplemente recargamos la página a la que accedimos anteriormente. Si hicimos correctamente los pasos anteriores, veremos lo siguiente desplazándonos un poco hacia abajo en la página:

¡Nuestra instancia de REDCap se conectó a la base de datos! Ahora debemos ingresar algunos parámetros de configuración de la plataforma, incluyendo algunos aspectos importantes de permisos para los usuarios de la plataforma. Hay en esta página elementos importantes a configurar:

• Allow normal users to create new projects?: Esta opción nos permite configurar si los usuarios normales, o sólo los administradores del sistema, pueden crear proyectos nuevos en REDCap. Un proyecto es un conjunto nuevo de formularios e instrumentos de captura de datos.
• Allow normal users to move projects to production?: Determina si los usuarios normales pueden poner “en producción” proyectos que hayan creado, o si sólo los administradores de la plataforma pueden hacerlo.
• Las otras variables tienen relación con los formatos deseados para la fecha, hora y números, datos de contacto del administrador del sistema (que serán visibles para los usuarios del software), y nombre de la institución. Se deberá completar estos datos, y finalmente, presionar el botón “Generate SQL Install script”:

Tras completar los datos, generamos el script de instalación que usaremos en el paso siguiente.

9. Se desplegará una página como la que se muestra en la siguiente imagen. Esta página contiene un cuadro de texto que contiene un GRAN script para la base de datos. Lo que tenemos que hacer es COPIARLO COMPLETAMENTE AL PORTAPAPELES (Edición > Copiar, o Ctrl+C en computadores con Windows), SIN OMITIR NINGUNA LÍNEA NI CARACTER, y llevarlo a MySQL Workbench para ejecutarlo tal como hicimos en el paso 6:

Esta página contiene el script que debemos copiar al portapapeles. Enfatizo nuevamente, EN SU TOTALIDAD.
Pegamos el script copiado en una ventana de consulta de MySQL Workbench, sustituyendo cualquier contenido que haya en la misma anteriormente, y lo ejecutamos con el botón que usamos en el paso 6 (el con el ícono del relámpago). Se ejecutará cada uno de los comandos del script, y veremos en la parte inferior el resultado de los mismos. Esto toma algunos segundos.

10. Completado lo anterior, volvemos a nuestro navegador, a la página desde la cual copiamos el script del paso anterior. Sólo entonces, haremos clic en el link que dice “REDCap Configuration Check”:

11. REDCap procederá a correr varios tests con la plataforma, y nos mostrará los resultados de los mismos indicándonos áreas que requieren acción. Entre los tests que aplicará, casi siempre habrá varios que fallarán inicialmente; esto es normal, y hay que ir tomando acción sobre ellos por separado. Particularmente importante es la configuración de los “Cron jobs” que REDCap requiere (procesos automatizados que corren a horas específicas durante el día) y la configuración del servidor de correo. En este tutorial no podemos cubrir cada uno de los posibles tests, pero son aspectos que deberían, en general, ser fáciles de corregir con la ayuda de sus departamentos de TI. Se muestra un ejemplo de esta pantalla:

De todas maneras, si hemos llegado hasta aquí, hacia el final de la página debiera estar el mensaje que se muestra a continuación:

12. Hemos instalado REDCap, ¡felicitaciones! Aún queda pendiente hacer algunas configuraciones de la plataforma y, muy especialmente, cargar el proyecto que deseemos (como, por ejemplo, el proyecto de seguimiento de Covid-19 compartido en el post de Alejandro, al principio de este tutorial). Podemos acceder al sistema en el link de la imagen anterior (donde dice “REDCap home page:”). ATENCIÓN: El sistema, en su configuración inicial, no tiene configurada la autenticación de usuarios, y se accede con un usuario genérico llamado “site_admin”. ¡ESTO DEBE SER CAMBIADO DE INMEDIATO! Para eso, debemos ir a “Control Center” en la barra superior:

Accedemos al Control Center…
Y luego vamos a “Add users (Table-based only)”. Para este ejemplo usaremos usuarios del mismo sistema REDCap; también es posible configurar el sistema para usar otros sistemas de autenticación corporativos, como LDAP.
Creamos un primer usuario que será el administrador. Llenamos los campos requeridos (nombre de usuario, nombre y apellido, y correo de contacto), vamos al final de la página y presionamos el botón “Save”. Con esto, si configuramos correctamente la conexión al servidor de correo, el usuario recibirá un correo con un link para configurar su contraseña inicial.
Volvemos al Control Center, y vamos a la opción “Administrators and Acct Managers”…
En el apartado “Designate an administrator”, seleccionamos el usuario que creamos recién en la lista desplegable, y presionamos el botón “Add as administrator”. Hecho eso, el usuario creado quedará como administrador de la plataforma.
Finalmente, vamos a la opción “Security and Authentication” en el Control Center…
Y seleccionamos la opción “Table-based” en la opción “Authentication method”, y al final de esa misma página, presionamos el botón “Save changes”. Esto habilitará la autenticación de usuarios propia de REDCap. En esta misma página es posible configurar muchas otras opciones, como integración con LDAP para autenticación corporativa, autenticación por dos factores, y muchas más, que caen fuera del alcance de este tutorial.

13. Para terminar este (casi eterno) tutorial, vamos a mostrar cómo configurar el idioma del sistema a español. Para esto, usaremos el otro archivo que descargamos al principio, en el paso 2; lo descomprimimos para obtener un archivo llamado “Spanish980.ini” (el número puede variar en función de la versión más actual al momento de hacer la descarga, y en general debe coincidir con el número de versión de REDCap que instalamos. En mi caso, difiere solamente en el último dígito, tengo REDCap 9.8.1). Este archivo debemos copiarlo al servidor (usando FileZilla o nuestro software FTP favorito), al directorio “languages”. Una vez subido el archivo, vamos nuevamente al Control Center, al apartado “General Configuration”:

Una vez ahí, si cargamos bien el archivo de idioma, se nos mostrará como opción en la lista desplegable titulada “Language Displayed for Global Pages”. Lo seleccionaremos, y luego hacemos clic en el botón “Save changes” al final de la página. Haremos exactamente lo mismo en el apartado “Default project settings” en el Control Center, y hacemos clic en “Save changes”. Haciendo esto, tendremos REDCap en español, y configurado para mostrarse en español para todos los proyectos nuevos que iniciemos en la plataforma:
Ajustamos el idioma en los ajustes generales. Hacemos el mismo paso en la opción “Default project settings” en el Control Center.
Nuestro REDCap ya está en español  Eso es todo para este tutorial. Hay muchísimas más opciones que configurar y ajustar, y se requiere estudiar bastante para poder habilitar una plataforma compleja como lo es REDCap, pero con estos primeros pasos creo que la aproximación inicial es un poco más amable. NO PODEMOS ofrecer soporte técnico para la instalación de la plataforma, dada la complejidad y variabilidad de cada institución que quiera instalarlo, pero la comunidad de REDCap ofrece mucha ayuda con la inmensa mayoría de los problemas y dudas más comunes que puedan surgir. Por supuesto alguna pregunta específica podemos tratar de abordarla en nuestro foro, dentro de nuestras posibilidades. ¡Muchos saludos!