Fat Free CRM: a Rails CRM you can self-host and extend with plugins

What Fat Free CRM solves, and who ends up running it

Commercial CRM suites bill per seat and keep your pipeline in someone else's database. Fat Free CRM takes the other route: a Rails application you host yourself, with the source available and the schema in your own Postgres, MySQL or SQLite instance. The README lists the out-of-the-box scope plainly: group collaboration, campaign and lead management, contact lists and opportunity tracking. Accounts, contacts, opportunities and tasks each have their own screens, and the README adds custom fields, tags, groups and teams on top of that core.

The audience is narrower than the feature list suggests. Anyone comfortable with a Rails deployment gets a CRM they can modify at the model layer. Anyone who wants a browser tab and a credit card will find this the wrong shape entirely, because there is no hosted edition described in the README. The project's own framing points at the same group: the README says specific features that are not 'Fat Free' in nature can be added by creating Rails Engines, and links a wiki page of available plugins for webhooks, record merging and time tracking. That is an invitation to developers, not to sales operations.

How the Rails app is put together

The repository layout is a conventional Rails application: app/, config/, db/, lib/, spec/, plus a fat_free_crm.gemspec that makes the same code installable as a gem. That dual identity is the architectural decision worth understanding. You can run the repository directly, or you can pull the gem into a separate Rails application and mount it as an Engine, which the README calls the best way to deploy if you need to add plugins or make customizations.

Data flows through ActiveRecord models in app/, with db/ holding migrations and seeds. The Dockerfile sets up a production-style image: it copies config/database.postgres.docker.yml to config/database.yml, installs ImageMagick and tzdata, then runs bundle install with deployment mode set. docker-compose.yml wires a web service to a postgres:16 service, passing DB_DATABASE, DB_USERNAME, DB_PASSWORD, DB_HOST and DB_PORT as environment variables and exposing ports 3000 and 80. The README still lists MySQL and SQLite as supported databases, so Postgres is a packaging choice in the Docker path rather than a hard requirement of the application.

Installing Fat Free CRM with Docker Compose

The README does not carry install commands itself; it points to separate guides for Linux or Mac OS, Heroku, Microsoft Windows (marked deprecated) and running as a Rails Engine. The Dockerfile comments do contain a working sequence, which is the shortest path to a running instance. The comments show creating the two volumes first, then bringing the stack up:

docker volume create pgdata
docker volume create gems
docker-compose up

The compose file builds the web image from the repository, links it to the db service, mounts the gems volume at /usr/local/rvm/gems and the pgdata volume for Postgres, and maps container ports 3000 and 80 to the host. RAILS_ENV and PASSENGER_APP_ENV are both set to production, and DB_HOST points at the db service with DB_PORT 5432.

With the stack running, the Dockerfile comments give the database and demo data step:

docker-compose exec web bundle exec rake db:create db:schema:load ffcrm:demo:load
docker-compose exec web bundle exec rails assets:precompile

The first command creates the database, loads the schema and pulls in demo records through the ffcrm:demo:load task. The second compiles assets so the interface renders correctly. After that the application is reachable on port 3000. The Dockerfile's own CMD is bundle exec rails s, and the image is built on ruby:3.4, while the README recommends Ruby 3.1 or later.

The Engine path is where customization lives

The README is direct about the trade-off: running as a Rails Engine is described as the best way to deploy if you need to add plugins or make customizations, and it notes that bolting Fat Free CRM into an existing Rails project is not yet simple. Those two sentences describe the same boundary from opposite sides. Extending the CRM is supported and the intended path. Folding it into an application you already have is a work in progress.

That pushes custom work into Rails Engines, which the README describes as the mechanism for features that are not 'Fat Free' in nature. The practical consequence is that any serious deployment eventually involves a second codebase: the CRM gem, plus your engine holding the additions. Teams that want a single tree to edit will find the repository itself more comfortable, at the cost of tracking upstream changes by hand. The README points to the wiki for engine information, so the details of writing one live outside the main document.

Where Fat Free CRM is the wrong tool

The README does not document rollback. It also does not describe a migration path between major versions beyond pointing at the release notes and CHANGELOG.md, which is thin for anyone running this in front of a sales team. Upgrades are a reading exercise, not a command.

Setup guides for Linux, Mac OS and Heroku are linked from the README, but the Microsoft Windows guide is explicitly marked deprecated, so Windows is not a supported deployment target in any current sense. The README also notes that the test suite, run by typing rake, takes a while, which matters if you plan to fork and maintain a customized copy. And the project's own feature scope stops at the CRM core: if you need a feature that is not 'Fat Free' in nature, the README's answer is to build an Engine, not to expect it upstream. Nothing in the README describes a mobile client, an offline mode or a public API contract, so teams that need those should treat them as absent until they find them documented.

How it compares with other open source CRMs

The related searches around this project include Bottle CRM and Python CRM options, which makes the language split the clearest difference. Fat Free CRM is Ruby on Rails end to end, installable as a gem, mountable as a Rails Engine, and extensible through more Rails code. A Python CRM such as Bottle CRM asks for a Python stack and its own deployment model instead. The choice between them is mostly a choice about which runtime your team already operates, because both put the database and the upgrade path in your hands.

Against commercial CRM platforms the difference is not features but ownership and cost structure. Fat Free CRM ships under the MIT license, with no seat count in the picture, and the README's plugin list covers webhooks, record merging and time tracking through community extensions rather than a vendor roadmap. The price is that you supply the hosting, the upgrades and the plugin maintenance. A hosted platform supplies those and charges for them.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-21, two days before this writing. The most recent release listed is v0.28.0 from 2026-04-19, following v0.27.0 and v0.26.1 earlier in April. That is a project still receiving commits, with releases arriving in bursts rather than on a fixed cadence.

Licensing is stated in two places that do not agree on their face. The README's For Developers section says Fat Free CRM is released under the MIT license, and the repository root carries both MIT-LICENSE and a NOASSERTION license classification. The README also embeds the full MIT permission text, with the copyright line reading 2008-2018 Michael Dvorkin and contributors. If license terms matter to your legal review, read MIT-LICENSE in the repository directly rather than relying on the README summary; this is a description of what the files say, not legal advice.

The upgrade cost is the reading itself. The README directs you to the release notes or CHANGELOG.md for detailed information on upgrading from previous versions, which means each version bump is a manual review of schema and configuration changes. Then come the standard Rails chores: bundle install against the Gemfile, database migrations from db/, and asset precompilation, which the Dockerfile comments run as rails assets:precompile. Custom Engines add a second upgrade surface on top, since they must keep working against the new core.

Editorial conclusion

Adopt Fat Free CRM if you have Ruby or Rails experience and want a self-hosted CRM whose data model you can extend through plugins or by mounting it as a Rails Engine. Do not adopt it if you need a hosted product with no server to run, or if your team cannot maintain a Rails deployment. Before committing, check the CHANGELOG and release notes for the upgrade path from your current version, confirm which database your deployment targets (the Dockerfile copies config/database.postgres.docker.yml over config/database.yml, so it is Postgres by default), and decide how customizations will be packaged, because the README says bolting Fat Free CRM into an existing Rails project is not yet simple.

Frequently asked questions

Official sources

1. fatfreecrm/fat_free_crm on GitHub
2. Issues
3. Project website
4. README
5. Releases