Running Fat Free CRM as a Rails Engine

These instructions are for users with moderate to advanced knowledge of Ruby on Rails.

Fat Free CRM can be run as either a standalone Rails Application (the standard way), or as a Rails Engine.

If you install Fat Free CRM in the standard way, you may run into problems if you make customizations, or install plugins. When your repository gets out of sync with the main codebase, you might find yourself frustrated by merge conflicts, or forgetting the things that you changed.

The advantage of running Fat Free CRM as an Engine is that your customizations can be kept separate from the main codebase. You can create a bare Rails application that packages your version of Fat Free CRM, as well as plugins, configuration and deployment scripts. You can update Fat Free CRM by simply changing the version number in your Gemfile.

To install and use Fat Free CRM as a Rails Engine, you just need to add the fat_free_crm gem to the Gemfile of your Rails 3.x application.

Important note: the engine features of Fat Free CRM are not fully completed yet. Whilst it works well installed as an engine on it’s own, there is still plenty of work required to namespace tables, models and controllers in order to enable Fat Free CRM to exist alongside other engines in the same application. Shared application authentication is also not implemented yet.

Clone and configure the example Rails app

1. Clone the ffcrm_app repo:

cd ~
git clone git://github.com/fatfreecrm/ffcrm_app.git

2. Change directory to ffcrm_app:

cd ffcrm_app

3. Set up database config:

Replace {database} with one of: postgres, mysql, mysql.mac, sqlite

cp config/database.{database}.yml config/database.yml
git add config/database.yml
git commit -m "Configured database"

4. Create database, run migrations, setup admin user, etc.:

rake ffcrm:setup

Add the Fat Free CRM gem to a new Rails application

1. At the command prompt, create a new Rails application:

rails new my_crm  # (where my_crm is the application name)

2. Change directory to my_crm:

cd my_crm

3. Remove a few files that fat_free_crm already provides:

(cd app && rm -f controllers/application_controller.rb \
views/layouts/application.html.erb helpers/application_helper.rb \
assets/javascripts/application.js assets/stylesheets/application.css)

4. Configure database.yml, specifying database authentication if necessary

5. Add the fat_free_crm gem to your Gemfile, with the following line:

gem 'fat_free_crm', :git => 'git://github.com/fatfreecrm/fat_free_crm.git'

6. Install gems:

bundle install

7. Add the following to config/application.rb after class Application < Rails::Application

Railties.engines.each do |engine|
  config.paths['db/migrate'] += engine.paths['db/migrate'].existent
end

8. Create database, run migrations, setup admin user, etc.:

rake ffcrm:setup

Fire it up

1. Start the web server:

rails server

2. Go to http://localhost:3000 and you’ll see your new site.

Troubleshooting

These are some of the errors that you may have encountered when deploying your fat_free_crm instance as a Rails Engine:

When making a comment on a lead that involves tagging another user (@username), you may notice that nothing gets posted and if you open up your javascript console, you would have noticed that you have gotten an Internal 500 Error.

To fix this,

1. Clone the actual fat_free_crm repository and copy config/settings.defaults.yml into your app’s config/settings.yml.

2. Be sure to fill in your SMTP details and that your delivery_method be uncommented.