====== MantisBT surveys ====== This document describes the setup and operations of the [[http://mantisbt.org/surveys/|MantisBT surveys]]. The tool we're using to manage surveys is an open-source solution called [[http://limesurvey.org|LimeSurvey]]. ===== Installation ===== ==== Web server setup ==== Edit the //mantisbt// site's configuration file (as root): * Add an alias: ''Alias /surveys /srv/www/surveys/'' * Reload apache configuration: ''service apache2 reload'' ==== LimeSurvey Setup ==== Reference: [[http://manual.limesurvey.org/wiki/Installation|LimeSurvey manual]] This installation procedure uses a [[https://github.com/mantisbt/LimeSurvey|fork of LimeSurvey's repository]] rather than relying on the distribution's packages. The **mantisbt** custom survey template was created based on the "Default Reloaded" template. See [[mantisbt:surveys#modifying_the_mantisbt_template|Modifying the mantisbt template]] for further details and instructions on how to further customize it. As of this writing, the //surveys// branch is based on LimeSurvey Release 2.00+ Build 130406. * Login as root * Install LimeSurvey code by initializing the repository <code> cd /srv/www git clone https://github.com/mantisbt/LimeSurvey.git surveys cd surveys git remote add upstream https://github.com/LimeSurvey/LimeSurvey.git git fetch upstream git checkout surveys </code> * Set directory permissions (section 7.1) <code> chgrp -R www-data tmp/ upload/ application/config/ chmod -R g+w tmp/ upload/ application/config/ </code> * Login to MySQL as root, and create the database and DB user (section 7.2) - replace XXX by the password <code> CREATE USER surveys@localhost IDENTIFIED BY 'XXX'; GRANT USAGE ON *.* TO surveys@localhost IDENTIFIED BY 'XXX'; CREATE DATABASE IF NOT EXISTS surveys; GRANT ALL PRIVILEGES ON surveys.* TO surveys@localhost; </code> * Navigate to http://mantisbt.org/surveys - this will start the LimeSurvey installer; follow the wizard * Select //English - English//, click **Start Installation** * **Accept** the license * Validate the requirements in the Pre-installation check and click **Next** \\ __Installation note__: in our case, the following libraries were missing: LDAP, imap but these are probably not needed * Database configuration: fill-in the fields ''MySQL, localhost, surveys, (password), surveys, (remove prefix)'' then click **Next** * Database settings: click **Populate database** * Optional settings * Enter admin user's //id// and //password// * Administrator email: ''firstname.lastname@example.org'' \\ __Installation note__: check with Victor if this should be changed to something else or if maybe we should create this address and make it redirect mails somewhere * Site name ''MantisBT.org Surveys'' * click **Next** * Confirm installation and click **Administration** * Login to LimeSurvey using the administrator's account created above * Create Survey Administrators (see User Administration section below) * Create user group * Edit Global Settings * Under //General// tab, set Default template to ''mantisbt'' * Set the //Email settings// as appropriate * //Bounce settings// email ''email@example.com'' * //Language// remove all except English (if we later decide to create surveys in other languages, we'll add them back in as needed) * Leave the other settings to their default values ===== Operations ===== ==== User Administration ==== The Administrator's account and password can be found in root user's ''~/passwd'' file. Individual accounts should be created for Survey Administrators and added as members of the //MantisBT// group * Create new user * Enter user id, e-mail and name then click //Add User// * Global permissions to set: uncheck all except //Participant panel//, //Create survey// * Template permissions: uncheck all except //mantisbt// * Add the new user to the //MantisBT// user group ==== Upgrading LimeSurvey ==== **Backup the code and the database before you start !!** Please refer to [[http://manual.limesurvey.org/wiki/Upgrading_from_a_previous_version#The_quick_way_.28for_minor_version_changes.29|LimeSurvey manual]] for generic upgrade instructions. This assumes a minor upgrade. Carefully review the LimeSurvey documentation as well as the release notes to make sure this process applies. If not, adjust as necessary. Make backups and tests ! Execute the commands below as root: <code> cd /srv/www/surveys tar -czf ../surveys-backup_$(date +'%Y%m%d-%H%M%S').tar.gz . git co master git pull upstream git co surveys git rebase ReleaseTagName </code> After completing this, login to LimeSurvey as admin and verify that the default template has not been changed * Go to //Global Settings//, //General// tab * If the //Default template// is not **mantisbt**, change it back and click //Save settings// Perform necessary tests to ensure the new version works as expected, and delete the backup file when no longer needed. ==== Modifying the mantisbt template ==== The relevant files can be found in the repository's [[https://github.com/mantisbt/LimeSurvey/tree/surveys|surveys branch]] (./upload/templates/mantisbt on the file system). To modify the template's source files (.pstpl, .css, image files, etc): * Clone the repository https://github.com/mantisbt/LimeSurvey * Check out the //surveys// branch * Make necessary changes * Test locally * Push Update the template on mantisbt.org (as root): <code> cd /srv/www/surveys git co surveys git pull </code> ===== Creating and managing Surveys ===== Surveys can be created directly [[http://mantisbt.org/surveys/admin/|on the server]]. Alternatively, for additional flexibility and better performance as well as to facilitate testing, the tool can be installed locally using a [[http://manual.limesurvey.org/wiki/Installation_of_the_LimeSurvey_XAMPP_package|XAMPP package]] provided by the LimeSurvey team. The survey can be uploaded to the server once it is ready. Please refer to the [[http://manual.limesurvey.org/wiki/English_Instructions_for_LimeSurvey|LimeSurvey manual]] for instructions, specifically the [[http://manual.limesurvey.org/wiki/Creating_surveys_-_Introduction|creating]] and [[http://manual.limesurvey.org/wiki/Managing_Surveys|managing]] surveys sections.