ELMO is a mobile data collection and analysis web application. Originally designed for the Carter Center for election observation missions, ELMO can be used in many different contexts for data collection.
Consider ELMO if you need:
- Integrated form design
- Standardized form sets
- Multiple data entry paths, including web, ODK Collect, and SMS
- Multiple mission/project management
- Advanced user management with multiple permission levels
- SMS broadcasting
- Custom, real-time reporting
To learn more about the history and goals of the project, visit the ELMO project site. You can also learn more about The Carter Center's Election Standards here.
In the future, we plan to offer managed instances of ELMO.
For an easy production setup, PaaS providers like Heroku or Engine Yard would work well for ELMO.
Or to setup an instance manually for development or production use, you can follow the instructions below.
Note that manually setting up a Rails application for production use can be a complicated process, and the best practices for doing so change regularly. Your best bet is a web search for something like 'deploying rails app to ubuntu'.
Note to install the software below we recommend the following package managers:
- Mac OS X: MacPorts or Homebrew
- Linux/Unix: bundled package manager (e.g. apt-get, yum)
- Windows: Npackd
-
Ruby 1.9.3+
-
Memcached 1.4+
- Ensure memcached is running before starting server, even for development, since caching is enabled in development and production environments.
- For production environments, ensure memcached is running on port 11219
- For development environments, be sure to increase the maximum size (limit_maxbytes) to at least 2 MB.
- MySQL 5.0+
- Create an empty database and accompanying user for use by the app (E.g. development database elmo_d with username elmo)
- Set up mysql for timezone support: See doc here
- Web Server
- If your instance is for development only, you can use Rails' built-in web server by running
rails s
, as discussed below. - If your instance is for production use, you will need a production-grade web server, such as nginx or Apache, and app server, such as Passenger, Unicorn, Thin, etc.
- Sphinx 2.0.6+
- Sphinx is an open source search engine.
- It should be available through any of the package managers listed above. If not it can be built from source.
- The Rails Gem that talks to Sphinx is called Thinking Sphinx.
- The Thinking Sphinx site is a good place to go for troubleshooting and documentation.
- Retrieve project files using Git
git clone https://github.com/thecartercenter/elmo.git
- Bundle, configure, and migrate
- Install the required gems by running
bundle install
in the project directory. - Copy
config/database.yml.example
toconfig/database.yml
and editdatabase.yml
to point to your database. - Copy
config/thinking_sphinx.yml.example
tothinking_sphinx.yml.example
and adjust any settings (usually not necessary). - Copy
config/initializers/local_config.rb.example
toconfig/initializers/local_config.rb
and adjust any settings. - Run database migrations:
rake db:migrate
. - Create an admin account:
rake db:create_admin
.
- Build the Sphinx index
- Run
rake ts:rebuild
- This should also start the Sphinx daemon (searchd). If at any time it needs to be restarted, you can also run
rake ts:start
- Run Whenever to setup cron jobs
- Run
whenever -i elmo
- Run
crontab -l
and verify that jobs have been added.
- Start the server
- For a development setup, just run
rails s
. - For a production setup, this will depend on your choice of servers, process monitors, etc., and goes beyond the scope of this document.
- Login
- Navigate to the app's URL (http://localhost:3000 by default in a development setup).
- Login using username admin and password temptemp (make sure to change the password).
- Create a new Mission and get started making forms!
ELMO is 100% open-source. We would like you to be part of the ELMO community! We accept and encourage contributions from the public. You can start by filing an bug report or feature request using the 'Issues' feature on Github. Or contact Tom Smyth for more info.
Contributors may find our auto-generated Entity-Relationship Diagram (ERD) useful.
You can generate it by running rake db:migrate
if adding new migrations or rake erd
to run on its own. To skip running it when doing migrations run NO_DIAGRAM=1 rake db:migrate
- Clone the Repo
git clone https://github.com/thecartercenter/elmo.git
- Create a New Branch
cd elmo
git checkout -b my_new_branch
- Code
- Adhere to common conventions in the existing code
- Include tests and make sure they pass
- Commit
- NEVER leave the commit message blank! Provide a detailed, clear, and complete description of your commit!
- If you have several commits, please make sure that they are squashed into one commit with a good summarizing commit message before pushing.
- Update Your Branch
git checkout master
git pull --rebase
- Fork
git remote add mine [email protected]:<username>/elmo.git
- Push to Your Remote
git push mine new_elmo_branch
- Issue a Pull Request
- Navigate to the ELMO repo you pushed to (e.g. https://github.com/username/elmo)
- Click "Pull Request"
- Write your branch name in the field (filled with "master" by default)
- Click "Update Commit Range"
- Verify the changes are included in the "Commits" tab
- Verify that the "Files Changed" include all your changes
- Enter details about your contribution with a meaningful title.
- Click "Send pull request"
- Feedback
The ELMO team may request changes to your code. Learning and communication is part of the open source process!
Parts of this document are based on the Discourse Project contribution guide at https://github.com/discourse/discourse/blob/master/CONTRIBUTING.md.