Merge branch 'release/0.4.1'

Author: pbchase

CHANGELOG.md

@@ -3,6 +3,11 @@ All notable changes to the REDCap Deployment project will be documented in this
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.1] - 2016-04-25
+### Changed
+- Correct documentation and make it more suitable for public consumption (Philip Chase)
+
+
 ## [0.4.0] - 2016-04-25
 ### Added
 - Enable ssl in apache config (Philip Chase)

README-hooks.md

@@ -12,10 +12,11 @@ activated. Activations can be global or project specific.
 
 ## Deployment
 
-Hooks are deployed with the script ./deploy_extensions.sh from the repo ssh://git
-@ctsit-forge.ctsi.ufl.edu/redcap\_deployment.git.
+Hooks are deployed with the script ./deploy_extensions.sh.  More specifically,
+the function _deploy\_hooks_ in deployment_functions.sh does the hook
+deployment.
 
-deploy_hooks.php requires a data file as input to indicate the scope of the
+deploy_hooks requires a data file as input to indicate the scope of the
 script, which hook will trigger it and the relative path to the script. A
 sample input file would look like this:
 
@@ -28,19 +29,27 @@ The activated hook list for the CTSI REDCap servers are in ./hooks/\<INSTANCE_NA
     redcap.ctsi.ufl.edu
     redcapstage.ctsi.ufl.edu
 
-deploy_hooks.sh will copy all the needed files from the redcap-extras repo to
-the hooks folder of the REDCap instance given the path to the appropriate data
-file.  On the CTSI Prod instance, you could deploy with this command:
+Deploy_hooks will copy all the needed files from the redcap-extras repo to
+the hooks/library folder of the REDCap instance. It will then activate hooks based on contents of the file ./hooks/\<INSTANCE_NAME\>data.csv.
 
-    sudo ./deploy_extensions.sh hooks/redcap.ctsi.ufl.edu/data.csv
+By default, it uses the UF CTSI production data for hook activation. To change this, specify an alternative configuration by exporting these 3 variables:
+
+    REDCAP_ROOT - the full path to the Apache document root of your redcap server
+    REDCAP_HOOKS - the full path the to hooks folder under $REDCAP_ROOT
+    HOOKS_CONFIGURATION - the name of the directory ./hooks/\<INSTANCE_NAME\> that has the correct data.csv
+
+e.g.
+
+    export REDCAP_ROOT=/var/https/redcap
+    export REDCAP_HOOKS=$REDCAP_ROOT/hooks
+    export HOOKS_CONFIGURATION=redcap.ctsi.ufl.edu
 
 
 ## Activate the hooking mechanism
 
 REDCap requires the hooking mechanism be activated in the Control Center.
 This is a system-wide setting.  The REDCap hooking mechanism must be activated
-by setting the Control Center -> General Configuration -> REDCap Hooks to
-'/var/https/redcap/hooks/redcap_hooks.php'
+by setting the Control Center -> General Configuration -> REDCap Hooks to the path to the redcap\_hooks.php file deployed by this repo.  For UF CTSI, this path is _/var/https/redcap/hooks/redcap\_hooks.php_
 
 
 ### Details

README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This repo documents the scripts and tools used by CTS-IT for  deployments and
+This repo documents the scripts and tools used by CTS-IT for deployments and
 upgrades to the CTSI REDCap staging and production instances. This repo
 includes a Vagrant VM on which these tools can be developed and tested.
 
@@ -13,10 +13,29 @@ production and staging instances of REDCap at the CTSI.
 ## Requirements
 
 A user of these tools will need to download and provide their own REDCap bits,
-downloaded from Vanderbilt. This REDCap .zip should be placed in the /vagrant folder.
+downloaded from Vanderbilt. This REDCap .zip should be placed in the root folder.
 It should not be renamed.
 
-This VM requires that Vagrant and VirtualBox be installed on the host system.
+This VM requires that Vagrant, VirtualBox and the vagrant-hostsupdater plugin be installed on the host system.
+
+See [Creating the Test VM With Vagrant](docs/creating_the_test_vm_with_vagrant.rst) for details on how to mee those requirements.
+
+
+## Using the Development environment
+
+To with the above requirements met, start the VM with the command
+
+    vagrant up
+
+After about two minutes, the VM should be accessible at [http://redcap.dev/redcap/](http://redcap.dev/redcap/) and at [https://redcap.dev/redcap/](https://redcap.dev/redcap/)
+
+
+## Hook and Plugin deployment
+
+CTSI REDCap Hooks and Plugins are deployed using the script
+deploy_extensions.sh in this repo.  This repo also contains the data files
+need to configure hook deployment for the CTSI REDCap instances.  See [Hook
+Deployment ](README-hooks.md) for usage instructions and details.
 
 
 ## REDCap upgrade
@@ -31,18 +50,20 @@ ToDo: Convert steps of wiki article to shell script.
 ## REDCap installation
 
 We do not currently have a bare-metal installation procedure. That said, the
-vagrant files presented in this repo contain many of the required steps in a
-deployment process. Other steps can be found in the above upgrade
+vagrant files presented in this repo contain many of the required steps in
+such a deployment process. Other steps can be found in the above upgrade
 instructions.
 
 ToDo: Make vagrant provisioning scripts more like a production deployment, but
 don't be too wed to the prod and stage instance we have today.  Make the
 deployment we _want_, not the deployment we have.
 
 
-## Hook deployment
+## Contributions
 
-CTSI REDCap Hooks are deployed using the script redcap_extensions.sh from this
-repo, ssh://[email protected]/redcap_deployment.git.  This repo
-also contains data files for CTSI REDCap Instance.  See [Hook Deployment
-](README-hooks.md) for usage instructions and details.
+This repository was created to meet the needs of the UF CTSI REDCap Team.  We
+have shared it as an example of how scripted deployments can be done in a
+Debian Linux environment.  We welcome contributions that parameterize our work
+to make these scripts more accessible to other REDCap sites.  Please fork this
+repository to commit and share your work.  Please make pull requests against
+the develop branch of this repo if you would like to make a contribution.

docs/creating_the_test_vm_with_vagrant.rst

@@ -6,7 +6,7 @@ Purpose
 
 The "vagrant" folder was created with the goal of making testing `REDCap <http
 ://project-redcap.org/>`__ and REDCap extensions as easy as possible.  The
-"vagrant" folder contains the `Vagrantfile <../vagrant/Vagrantfile>`__ which
+root folder contains the `Vagrantfile <Vagrantfile>`__ which
 allows you to start a virtual machine capable of running the `REDCap software
 <http://http://www.project-redcap.org>`__.  This virtual machine will install
 Apache and MySQL software without any user intervention.  If provided with a
@@ -19,6 +19,7 @@ RED-I to import data into a sample REDCap project:
 -  You have to obtain the REDCap software from http://project-redcap.org/
 -  You have to install the **Vagrant** software
 -  You have to install the **Virtual Box** software or another virtual machine provider.  For this discussion we will assume Virtual Box is the virtual machine provider for Vagrant.
+-  You have to install the Vagrant hostsupdater plugin
 
 Steps
 -----
@@ -43,31 +44,39 @@ On Mac OSX users using brew can install these packages using brew cask:
 - brew cask install virtualbox
 - brew cask install vagrant
 
+
+2. Install Hosts updater plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Vagrant will need one plugin for this VM.  On any platform:
+
+-  vagrant plugin install vagrant-hostsupdater
+
 For more details about Vagrant software you can go to
 `why-vagrant <https://docs.vagrantup.com/v2/why-vagrant/>`__ page.
 
-2. Get your REDCap zip file
-~~~~~~~~~~~~~~~~~~~
+
+3. Get your REDCap zip file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As mentioned above you have to obtain a copy of the REDCap software from http
 ://project-redcap.org/.  Save the file with its default name to ./vagrant
 folder.  This ensures that in the provisioning script `bootstrap.sh
-<../vagrant/bootstrap.sh>`__ script can extract the files to the virtual
+<bootstrap.sh>`__ script can extract the files to the virtual
 machine path "**/var/www/redcap**\ ".
 
 If you put multiple redcap*.zip files in the vagrant folder, the provisioning
 script will use the one with the highest version number.
 
-3. Start the VM
+4. Start the VM
 ~~~~~~~~~~~~~~~
 
 Follow this procedure to start the REDCap VM:
 
 .. raw:: html
 
    <pre>
-   # must be in the redi/vagrant/ directory
-   cd ./vagrant
+   # must be in the root directory of this repository
    vagrant up
    </pre>
 
@@ -87,17 +96,13 @@ message like this at the end of the log:
 
 The REDCap web application should be accessible in the browser at
 
-http://localhost:8080/redcap/
-
-If port 8080 is already in use on your computer Vagrant will choose a
-different port automatically. Read the log of "vagrant up" and note the port
-to be used.
+http://redcap.dev/redcap/
 
 The REDCap instance will be setup with the sample projects that shipped with
 that REDCap zip file.
 
 
-4. Verify the VM is running via the console
+5. Verify the VM is running via the console
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also verify the virtual machine is working properly by accessing it