Setup Linux or Mac OS

Installation on Linux or Mac OS

Important Notes:

1. If you want to try out a one-click installer (gives you everything you need to get started), take a look at https://bitnami.com/stack/fat-free-crm/installer.
2. To install rvm, ruby and rails (gives you every prerequisite you need to continue with this one), take a look at rvm.io.

Clone

Grab a copy of FatFreeCRM from GitHub

$ git clone git@github.com:fatfreecrm/fat_free_crm.git fat_free_crm

Change current working directory to previously created one

$ cd fat_free_crm

Set Up Configuration (Database & Settings)

Fat Free CRM supports PostGreSQL, MySQL and SQLite databases. The source code comes with
sample database configuration files. You will need to copy the config for your chosen db:

• MySQL: cp config/database.mysql.yml config/database.yml
• PostgreSQL: cp config/database.postgres.yml config/database.yml
• SQLite: cp config/database.sqlite.yml config/database.yml

Edit config/database.yml and specify database names and authentication details.

• Then, create an environment variable with your chosen database or change default pg within else clause.

# Uncomment the database that you have configured in config/database.yml
# ----------------------------------------------------------------------

case ENV['CI'] && ENV['DB']
when 'sqlite'
  gem 'sqlite3', '~> 1.3.13'
when 'mysql'
  gem 'mysql2'
when 'postgres'
  gem 'pg'
else
  gem 'pg'
end

Install Gem Dependencies

You may need to install some platform specific libraries to satisfy all the gem dependencies.

• RedHat (e.g. CentOS)

sudo yum install ImageMagick-devel libxml2 libxml2-devel libxslt libxslt-devel

Then one of the following lines:

sudo yum install mysql mysql-devel mysql-server
sudo yum install postgresql postgresql-devel postgresql-libs postgresql-server

• Debian (e.g Ubuntu)

sudo apt-get install libmagick++-dev libxml2 libxml2-dev libxslt1.1 libxslt1-dev libyaml-dev

Then one of the following lines:

sudo apt-get install mysql-client libmysqlclient-dev
sudo apt-get install postgresql-9.3 postgresql-client-9.3 libpq-dev

• Mac OS

Using Homebrew

brew update && brew install postgresql

If you have trouble installing the DB dependencies, you will need to refer to either the MySQL or Postgres documentation for installation on your platform, before continuing.

Once the above is complete, run the following command from the application’s root directory:

bundle install

Create Database

Now you are ready to create the database:

rake db:create

Configure Application (Optional)

You can configure Fat Free CRM settings, such as your host, base URL, language (locale),
menu structures, default colors, and email authentication.

Fat Free CRM settings are stored in three places, and are loaded in the following order:

1. config/settings.default.yml
2. config/settings.yml (if exists)
3. ‘settings’ table in database (if exists)

Settings loaded last have the highest priority, and override any settings from the previous sources.

To override any settings:

• Create a blank file at config/settings.yml
• Copy the settings that you want to override from config/settings.default.yml,
  and configure the values.
• Commit config/settings.yml to the git repo with the following commands:

git add -f config/settings.yml
git commit -m "Added config/settings.yml"

Example: If all you want to do is change the language to French, your config/settings.yml file only needs to contain the following line:

:locale: "fr"

Run database migrations and set up an admin user

Run the following rake task:

rake ffcrm:setup

The previous command will migrate the database and prompt you for an admin user name, password and email.
If you want to run the setup procedures without any user input, you can use the following (useful for automated server deployments):

rake db:migrate && rake ffcrm:setup:admin USERNAME=admin PASSWORD=password EMAIL=admin@example.com

If you got an error like

TZInfo::DataSourceNotFound: tzinfo-data is not present. Please add gem 'tzinfo-data' to your Gemfile and run bundle install

See Troubleshooting section

Load Demo Data (Optional)

You can test drive Fat Free CRM by loading sample records that are generated
on the fly mimic the actual use.

IMPORTANT: Loading demo will delete all existing data from your database.

rake ffcrm:demo:load

Among other things the demo generator creates 8 sample user records with the following usernames:

Username	Password
aaron	aaron
ben	ben
cindy	cindy
dan	dan
elizabeth	elizabeth
frank	frank
george	george
heather	heather

The demo site at http://demo.fatfreecrm.com provides access as a sample user as well.

Note: You can reset the database and reload demo data at any time by using rake ffcrm:demo:reload

Run the App

Now you should be able to launch the Rails server and point your web browser
to http://localhost:3000

rails server

Troubleshooting

Something isn’t working for you? Maybe the following will help:

TZInfo::DataSourceNotFound: tzinfo-data is not present.

Please add gem ‘tzinfo-data’ to your Gemfile and run bundle install

If you already have gem ‘tzinfo-data’ my the following be your solution

$ sudo apt-get install tzdata

Trouble installing on OSX Big Sur (11.4) and later

fat_free_crm has a dependency on libv8 via mini_racer that does not currently support Apple M1 silicon: https://github.com/rubyjs/libv8/issues/309

If you are not on Apple silicon and your install is failing to install mimemagic you are probably missing shared mime info. Install this with

brew install shared-mime-info