Skip to content
Switch branches/tags
Go to file
This branch is 569 commits ahead of openplans:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


TODO This needs to be updated to reflect upgraded environments. Most notably: No more spork, use built-in Spring; Add reference to VM setup docs in Recipes repo; Remove 'updating Ruby to a newer version' instructions and replace with reference to Server setup docs in Recipes repo


WiseGuide is a CRM for rider training programs, such as RideWise.

Funding is provided by Ride Connection, and software development
by OpenPlans and Panoptic Development.

Development Environment

Install RVM

RVM is a ruby package manager that keeps all the ruby packages for a
given project isolated in a single environment.  It's extremely useful
for locking down the environment for your project.  To learn more, check

To install rvm, run these two commands:

    bash < <(curl -s )
    echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" # Load RVM function' >> ~/.bash_profile

Open a fresh terminal (or re-source your `.bash_profile`), and then follow the
next step to install dependencies.

Install dependencies

When you change to the wiseguide project directory, you will be prompted by
RVM to trust the .rvmrc, answer yes to the prompt.  After this, you may be
prompted to install the required Ruby version; do so if necessary.

Now that your rvm is ready, install the wiseguide dependencies:

    bundle install

Copy config/database.yml.example to database.yml and tweak to suit your
needs.  (It works out of the box if you're working with SQLite. Fuzzy
matching is not present in SQLite, however.)

Copy `config/app_config_template.yml` to `app_config.yml` and tweak to suit
your needs. (You will want to put your email address in there at least.)

Bootstrap environment

Populate the database:

    bundle exec rake db:setup

In a development environment, you can load some fake sandbox data with:

    bundle exec rake db:sandbox:load

It will create (among other things) an initial admin account, so you can login
as '' with password 'password 1'.
That's it!  You can now run a development server with `rails s`.

Resetting the development database

In the event you need to reset the database, the following command will perform
all of the necessary steps:

    bundle exec rake db:drop:all && bundle exec rake db:create:all \
        && bundle exec rake db:migrate && bundle exec rake db:seed \
        && bundle exec rake db:sandbox:load && bundle exec rake db:test:prepare


We are using Rspec for unit testing and cucumber for integration and functional
testing. You can run them using the following commands:

    bundle exec rake spec
    bundle exec rake cucumber

(Just `bundle exec rake` will run all of the tests.)

Speeding up your tests

The spork gem has been included and preconfigured in order to help speed up the 
execution of tests. If you are only going to be running the test suite once or 
need to setup a CI server, you won't want to use spork. But if you will be
running tests frequently, while developing a new feature or refactoring, etc., 
then preloading your test environment into spork will save you a few seconds 
or minutes per test execution. To use spork while testing, first boot up spork:

    bundle exec spork
for Rspec tests, or 
    bundle exec spork cucumber
for running Cucumber features. Note that these two servers can be run in the 
background simultaneously as they use different ports.  The `--drb` option has
been enabled by default, so the tests will automatically use the spork server
if it is running.

Note that because spork preloads your environment, you will have to restart the
spork server anytime you modify your model or configuration files, or anything
else that will be cached by the Rails server.

See also:



There are two different deployment environments: staging and production.
Staging runs the `master` branch, to test the latest features that have been
developed.  Production runs the `stable` branch, which should contain commits
that have been tested on staging successfully.

During normal development, you should always be committing to `master`. After
testing the new features on the staging server, you can check out `stable` and
`git merge master` to prepare to deploy them to production.


This application uses capistrano for deployment.  Check out config/deploy.rb 
and config/deploy/ for basic deployment recipes and configuration.

Deployment uses key-based authentication. To deploy, you'll need to add your 
public key on the staging/production servers so you can run commands as the 
"deployer" user.

To set this up, talk to another developer to get your public key on the 
machines. If you need to do system administration on the servers, you'll need 
your own user accout set up as well.

Once you have SSH access as deployer, you can deploy:

 run: `cap [staging|production] deploy`

Remember to push your changes to the main repository first, since the deploy
process pulls from there.  Database migrations are currently performed by hand
after deploying.

PostgreSQL Notes

To set up PostgreSQL for use with WiseGuide, you will need the fuzzystrmatch
library (included in postgresql-contrib-8.4 in Ubuntu).  This adds support for
dmetaphone, which is how we phonetically match names.  Run `psql` (usually as
the `postgres` user) and then the following command:

    \i /opt/local/share/postgresql84/contrib/fuzzystrmatch.sql 

Fuzzystrmatch setup with Homebrew on Mac

Fuzzystrmatch should be included when you install postgres with Homebrew. If
the following directions don't work for you, first try updating homebrew with 
`brew update`, then upgrade postgres with `brew upgrade postgres`. (Note that 
a major version upgrade may cause your databases to need to be migrated. To be 
safe, first export them all as SQL dumps and store them somewhere safe.) Then
try these steps again.

1. Make sure postgres is running
2. run `psql -d {your_database_name}` to login to your database
3. Once logged in, execute the statement `CREATE EXTENSION fuzzystrmatch;`
4. It should return "CREATE EXTENSION" if it is successful, or "extension 
"fuzzystrmatch" already exists" if the library is already installed
5. Repeat this process for each database you will need it in (development, 
test, production, etc.)

If you plan on running any of the tests that require dmetaphone to be present
you should consider running the above commands on the `template1` database
which Postgres uses as the template for creating new databases. Otherwise,
you will need to repeat this process anytime the databases are rebuilt from 
one of the destructive `rake db:...` commands.

Server Notes

The servers currently run Apache + Passenger (a.k.a. `mod_rails`) to host the
application.  The installation is fairly straightforward (see the Passenger

When updating Ruby to a newer version, you need to make a few changes:

1. As deployer, run the `rvm install` command for the new Ruby version.
2. Deploy as normal, which will make sure the bundle is up to date.
3. As deployer, `gem install passenger`
4. Reinstall Apache module: `passenger-install-apache2-module`
5. Update both /etc/apache2/mods-enabled/passenger.load and conf as directed
   by the previous command. (The paths will have changed.)
6. Restart Apache.


A CRM for rider training programs




No releases published


No packages published