REDCap Install Config - FreeBSD #88
Description
Initial draft of installing and configuring a baseline default REDCap instance on FreeBSD. Still needs:
- Fixing various post-install issues dealing with web directory permissions, email, cron jobs, etc.
- Set up proper authentication method
- Notes for configuring a separate reverse proxy
- Notes for configuring an external database server
- Info about separating out secrets from the web root directory
- Moving edocs to a different location and/or volume
- Downloading REDCap updates via
curl - Steps for installing of FreeBSD from scratch
- Properly setting up REDCap redirect within nginx - This is to handle old links to REDCap (e.g.,
redcap_v15.5.30) that users might have bookmarked. When the version folder is deleted with in the web root directory, REDCap does not redirect automatically.
REDCap Install Config - FreeBSD
REDCap is a web-based software application that is created and maintained by Vanderbilt University: https://www.project-redcap.org/
Vanderbilt maintains a document describing their software requirements: https://projectredcap.org/software/requirements/
REDCap is downloaded from Vanderbilt's website, which is only accessible by those who have a license agreement with REDCap to use their software. Once there, you have the option of selecting the Standard Release or the Long-Term Support (LTS) Release.
DOM IT uses the Standard Release for its projects. Once the version is selected, then you are given the option to pick which version you want to download and whether or not you want to download a Fresh Install Package or an Update Package.
Download the Fresh Install Package from REDCap listed above, which is redcap16.1.5.zip as of 2026-03-05.
Install baseline packages
-
Install nginx
pkg install nginx-devel sysrc nginx_enable=YES
-
Install php-fpm
pkg install php84 php84-{ctype,curl,dom,fileinfo,filter,gd,iconv,ldap,mbstring,mysqli,opcache,pdo,pdo_mysql,pecl-imagick,posix,session,simplexml,sockets,tokenizer,xml,xmlreader,xmlwriter,zip,zlib} sysrc php_fpm_enable=YES -
Install mariadb
pkg install mariadb118-server mariadb118-client sysrc mysql_enable=YES mysql_secure_installation
Copy the installation package to the application server from your local machine.
scp -P 22 /location/of/software/redcap16.1.5.zip username@172.16.80.233:/home/username
Move and unpack the installation package to a new web directory. Note: mkdir -p below will create all directories as needed at once. That's why I don't have multiple mkdir statements.
mv /home/username/redcap16.1.5.zip .
mkdir -p /usr/local/www/redcap/public_html
unzip redcap16.1.5.zip -d redcap16.1.5
mv redcap16.1.5/redcap/* /usr/local/www/redcap/public_htmlYou want to keep the web directory permissions at root:wheel. Grant read permissions on that directory to let nginx server those files. Make sure you execute the permission changes in order. Note: This will prevent you from using REDCap's Easy Upgrade functionality that allows you to upgrade REDCap within the app itself. For security reasons, this is no longer recommended on production servers. Upgrades will need to be performed manually on the server itself by copying the files to the php server.
chmod -R 0750 /usr/local/www/redcap/public_html
find /usr/local/www/redcap -type d -exec chmod 0755 {} \;
find /usr/local/www/redcap -type f -exec chmod 0644 {} \;Configure basic web server
At this point, the instructions are going to continue with a basic default installation with no customization of the web server, php, or mariadb. Items like REDCap redirection for old links, setting up a reverse proxy, php caching, configuring mariadb's memory settings will be done later.
Modify nginx.conf
Go ahead and configure nginx to serve the public_html folder. Note: this configuration only handles non-secure traffic on port 80
vim /usr/local/etc/nginx/nginx.confuser www;
worker_processes 1;
pid /var/run/nginx.pid;
events {
worker_connections 2048;
use kqueue;
}
http {
include mime.types;
default_type application/octet-stream;
index index.php index.htm index.html;
sendfile on;
server_tokens off;
server_names_hash_bucket_size 128;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 4;
gzip_min_length 256;
gzip_types application/dash+xml application/eot application/font application/font-sfnt application/javascript application/json application/opentype application/otf application/pdf application/pkcs7-mime application/protobuf application/rss+xml application/truetype application/ttf application/vnd.apple.mpegurl application/vnd.mapbox-vector-tile application/vnd.ms-fontobject application/wasm application/x-font-opentype application/x-font-truetype application/x-font-ttf application/x-httpd-cgi application/x-javascript application/x-mpegurl application/x-opentype application/x-otf application/x-perl application/x-ttf application/xhtml+xml application/xml font/eot font/opentype font/otf font/ttf image/svg+xml text/css text/csv text/javascript text/js text/plain text/richtext text/tab-separated-values text/x-component text/x-java-source text/x-script text/xml vnd.apple.mpegurl;
server {
listen 80;
server_name localhost;
client_max_body_size 500m;
root /usr/local/www/redcap/public_html/;
location = /robots.txt {
add_header Content-Type text/plain;
return 200 "User-agent: *\nDisallow: /\n";
}
location ~* /temp/* {
return 404;
}
location ~ /\. {
deny all;
access_log off;
log_not_found off;
}
location / {
try_files $uri $uri/ =404;
}
location ~* \.(?:ogg|ogv|svg|svgz|eot|otf|woff|mp4|ttf|css|rss|atom|js|jpg|jpeg|gif|png|ico|zip|tgz|gz|rar|bz2|doc|xls|exe|ppt|tar|mid|midi|wav|bmp|rtf)$ {
expires max;
log_not_found off;
access_log off;
}
location = /favicon.ico {
alias /usr/local/www/redcap/public_html/img/favicon.ico;
}
location ~* \.php$ {
include fastcgi_params;
try_files $uri @notfound;
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param HTTP_PROXY "";
fastcgi_read_timeout 300;
fastcgi_hide_header X-Powered-By;
fastcgi_hide_header Server;
fastcgi_hide_header X-AspNetMvc-Version;
fastcgi_hide_header X-AspNet-Version;
}
location @notfound {
rewrite ^(/redcap_v\d+\.\d+\.\d+/.*)$ /redcap_redirect.php last;
}
}
}Configure php_fpm
Modify some basics in php.ini. You will need to modify the memory_limit, post_max_size, and upload_max_size (among other settings) to best fit your needs and server resources.
php.ini
cp /usr/local/etc/php.ini-production /usr/local/etc/php.ini
vim /usr/local/etc/php.iniexpose_php = Off
max_input_vars = 100000
memory_limit = 1G
post_max_size = 256M
upload_max_filesize = 256M
date.timezone = America/Chicago
session.cookie_secure = 1www.conf
Configure the PHP process manager www.conf for the child creation method you want.
vim /usr/local/etc/php-fpm.d/www.confuser = www
group = www
listen = 127.0.0.1:9000
listen.backlog = -1
listen.owner = www
listen.group = www
listen.mode = 0660
listen.allowed_clients = 127.0.0.1
pm = ondemand
pm.max_children = 15
pm.process_idle_timeout = 10s;
pm.max_requests = 200Restart services
After making all of these changes, restart the services.
service nginx restart
service php_fpm restartStart REDCap web installation
Open a wen browser and point it to your IP address of the server. Since REDCap's database has not been configured you should see the following messafe displaying CRITICAL ERROR: REDCap server is offline!.
To start the installation, append /install.php to the url (e.g., http://172.16.80.233/install.php).
Step 1 is to create the REDCap database and user in mariadb.
CREATE DATABASE IF NOT EXISTS `redcap`;
CREATE USER 'redcap_user'@'%' 'password_for_redcap_user';
GRANT SELECT, INSERT, UPDATE, DELETE ON `redcap`.* TO 'redcap_user'@'%';Modify database.php to use these database credentials.
vim /usr/local/www/redcap/public_html/database.php<?php
// For security reasons, move these database connection variables
// variables to a file outside the web root directory
$hostname = '127.0.0.1';
$db = 'redcap';
$username = 'redcap_user';
$password = 'password_for_redcap_user';
// Make sure to set the $salt
$salt = 'Generate a long random alphanumeric string';Refresh your web browser to reload /install.php with the modified database.php in place. If everything worked, you should see a green success message saying Connection to the MySQL database 'redcap' was successful! and an additional step listed. This is where you will need to set up information about your institution, contact information, formatting, and whether to create table-based users. For simplicity, go ahead and click the Generate SQL Install Script button.
The install page should show new steps and the database script to generate the tables. Click the Download SQL button and save the resulting redcap_install.sql file. Copy this file to the server using any method you want.
scp -P 22 ~/Downloads/redcap_install.sql username@172.16.80.233:/home/username
Log on to the server and execute the SQL script.
mariadb -u root redcap < redcap_install.sql
After it completes, go back to browser and proceed to the next step and click on the REDCap Configuration Check link (e.g., http://172.16.80.233/redcap_v16.1.5/ControlCenter/check.php?upgradeinstall=1). You will see different areas in green, yellow, and red. The red sections need to be addressed to properly finish configuring REDCap. The yellow sections are recommendations, but should be fixed as well.
