SugarCRM SupportPoliciesEnvironmentsDevelopment EnvironmentsOSX Development Environment

OSX Development Environment

Provided with each requirement below is a command that can install the software for OSX. Please feel free to install the required software on your own, but, if you plan on following our suggested commands, you must prep your Mac by installing Homebrew and Cask (package management tools for OSX) then configuring it with appropriate package sources. We also strongly recommend installing Xcode tools since this generally includes Git as well as a number of handy developer tools that you may eventually need.

Access to Sugar source code is available via Download Manager once you become a Sugar Partner or a Sugar Customer.  This is also where you will get your subscription keys that will allow you to run Sugar to test your changes.

Many of the instructions here are similar to what you can find in the official Sugar Installation and Upgrade Guide, so, if you have problems or questions, you may want to start there. 

Homebrew Setup

Homebrew is a simple and popular command line package management tool for OSX.

Open a Terminal window and run the following commands.  The first command below installs Homebrew, the others install Cask and set up package sources that are used later in these instructions.

ruby -e "$(curl -fsSL"
brew tap caskroom/cask
brew install cask brew tap caskroom/versions brew tap homebrew/core brew tap homebrew/homebrew-php

Installing required software

An IDE (such as PHPStorm)

PHPStorm is our preferred IDE and used by the entire Sugar Engineering team.  It has strong PHP and JavaScript support as well as a great integration with Git.  It does cost money, so you can substitute this if you feel more comfortable with another (free) IDE instead like Eclipse, Xcode, or NetBeans. It is useful to also be proficient in lightweight text editors like VI, TextWrangler, or Sublime when you want to quickly edit config files, etc.

 brew cask install phpstorm


The first command below will install MySQL, but feel free to replace it with one of our other supported databases instead.  MySQL is free.  The second command starts up a local MySQL Server.  While you can always setup Sugar to access an external database server, having a local copy of MySQL running on your machine is convenient for debug and config.

brew install mysql@5.7
brew services start mysql


These commands will install some PHP dependencies that Sugar uses, PHP 7.1 itself and a few other helpful tools.  PHP is free.

brew install autoconf gettext jpeg libpng openssl zlib freetype imap-uw mcrypt pcre
brew install php71 --with-imap --with-httpd24 brew install composer


Elasticsearch is the full text search engine required by Sugar.  Elasticsearch requires Java, so begin by installing Java:

brew cask install java 

Then follow the instructions on the Elasticsearch Installation Guide to install Elasticsearch 5.4.  


Apache is the supported HTTP web server on OSX and it should already be installed on your Mac.  You can test that it's working by running the following command.

sudo apachectl start

Now visit http://localhost/ in your browser and verify that it works!

Configuring required software

After installing the above required software, we recommend executing the following list of commands prior to installing Sugar.

1. Set up MySQL root password and secure MySQL Server

This script allows you to set your MySQL root password (not your Mac's root password) for your MySQL Server as well as prompt you to enable safe default security settings. The default MySQL root password should be blank.  We recommend answering YES to each security prompt.


2. Set up PHP configuration with good defaults for Sugar development

Edit the php.ini for the version of PHP you've just installed in order to get some defaults set up so you can run Sugar 7 in a development configuration.

cd /usr/local/etc/php/7.1
open php.ini

Adjust PHP error reporting levels so that the majority of messages are logged.

error_reporting = E_ALL & ~E_STRICT

Make sure that error messages are visible in page output when possible.

display_errors = On

Set larger PHP memory limit for requests.  Memory limit needs to be relatively large to handle occasional rebuild of Sugar metadata cache.

memory_limit = 256M

Allow for larger file uploads such as document attachments or Sugar module loadable packages.

upload_max_filesize = 20M

Set your default time zone.  This is an example.

date.timezone = America/New_York

Save these changes.  These changes won't go into effect until you've restarted Apache!  We will do this in the next step.  For more details on these and other php.ini settings, please refer to the PHP Manual.


3. Setting up Apache

There are many different ways to set up Apache.  Explaining every possible way is outside the scope of this article.  For a detailed explanation of the web server settings and file permissions needed to run Sugar, check out the Web Server topic in the Installation and Upgrade Guide.

If don't have a preference for how Apache is setup, we recommend configuring Apache to run the Sugar application out of your home directory as described below.  Please feel free to adapt anything below for your own purposes.

First, you'll want to stop Apache if it is currently running.

sudo apachectl stop

Run the following command in your Terminal window to discover what version of Apache you're running.

apachectl -v

Update /etc/apache2/users/USER_NAME.cnf with the appropriate config below based upon your Apache version. Remember to replace USER_NAME with your OSX username in the examples below.

Apache 2.4.x

# Load homebrew php71 module
LoadModule php7_module    /usr/local/Cellar/php@7.1/7.1.16/lib/httpd/modules/

Group staff
# Necessary Apache 2.4 directives for Sugar install directory <Directory "/Users/USER_NAME/Sites/"> Options Indexes FollowSymLinks MultiViews AllowOverride All Require all granted </Directory>

Lets make sure that Apache and PHP are configured properly.  Create the ~/Sites directory if it does not already exist.  Then create the following file under your ~/Sites directory.




Start your Apache server.

sudo apachectl start

Open your browser and navigate to http://localhost/~USER_NAME/index.php.

You should then see a screen like the one below.



This page lists all of your PHP configuration settings.  

Verify the Loaded Configuration File listed is the same file that you updated in Step 2 above.  If not, make the updates to the Loaded Configuration File.  Remember to restart Apache after making any php.ini changes.

Verify that the following configurations are displayed.  If the configurations are incorrect, make changes (see Step 2 above if you need further instructions) and restart Apache.

Directive Local Value Master Value
error_reporting 30719 30719
display_errors On On
memory_limit 256M 256M
upload_max_filesize 20M 20M
date.timezone America/New_York America/New_York


Still having trouble?

It may be because the userdir module isn't loaded, the configuration isn't setup correctly, or that mod_rewrite is disabled. Try uncommenting the directives below to see if they help. 

In /etc/apache2/httpd.conf:

LoadModule userdir_module libexec/apache2/
LoadModule rewrite_module libexec/apache2/

Include /private/etc/apache2/extra/httpd-userdir.conf

# Some yosemite versions (betas) might need these uncommented also
#LoadModule authz_host_module libexec/apache2/
#LoadModule authz_core_module libexec/apache2/

In /etc/apache2/extra/httpd-userdir.conf:

Include /private/etc/apache2/users/*.conf

If you're still stuck, you'll need to troubleshoot more on your own. Refer to the Installation and Upgrade Guide or ask a question in the Sugar Developer Community.

4. Sugar Time!

At this point, if you have Apache, Elasticsearch & MySQL all running, then you are ready to install Sugar.

If you are an official Sugar Developer, Partner, or Customer then you can download the Sugar application from Download Manager as described in the Installation and Upgrade Guide.

Unzip your Sugar application download into the ~/Sites directory.  You may want to rename your Sugar directory to something like sugarcrm.

Also make sure to setup file permissions as described in the Web Server section of the install guide.  Sugar will write a lot of files to disk and the Apache user needs to have appropriate permissions to certain files and directories to do this.  The quick and dirty solution for development environments only is to run the following.  

chmod -R 777 {Sugar Directory} 

For production environments, we recommend following all directions in the On-Site Installation Guide.

Once file permissions are setup appropriately, you can run the Sugar installer.  You can do this easily from your web browser.  If you've unzipped and renamed your Sugar application to ~/Sites/sugarcrm/ then you can launch http://localhost/~USER_NAME/sugarcrm/, which should automatically redirect you to install.php and launch the Sugar installation wizard.


Follow the steps in the installation wizard to setup your Sugar application.  When in doubt, just use the default values populated in the wizard.

For Download Key, enter the subscription key you received when you became a Sugar Developer/Partner/Customer.

On the Database Configuration page,

  • For Database Administrator Username / Password, you can use the root username and password configured for MySQL in Step 1.
  • For Populate Database with Demo data, you will probably want to select YES.  Having data put into Sugar automatically is convenient for development and debugging purposes.  It does make the installation take a bit longer while data is generated and inserted.

Once installation is complete you are redirected to the Sugar login page.  You should be able to use the Sugar Admin username and password (different from the Database Admin username and password) you setup during installation to login!

Silent Installation Config

Throughout development, you may find yourself wanting to start over with a fresh installation of Sugar.  To speed subsequent installs, you can use a silent install configuration file.  The file has configurable options to automatically enable Developer Mode, install demo data, and more.  

To do a silent install, create a new file named config_si.php and place it under your Sugar application directory.  Paste the code below in to your new config_si.php, and edit the code as you desire.  Once config_si.php is in place, the silent install will run automatically when you navigate to http://localhost:8080/sugar/install.php in your browser.


$sugar_config_si = array (
 'setup_db_host_name' => 'localhost',
 'setup_db_database_name' => 'sugarcrm',
 'setup_db_drop_tables' => 1,
 'setup_db_create_database' => 1,
 'demoData' => 'yes',
 'developerMode' => 1,
 'setup_site_admin_user_name' => 'admin',
 'setup_site_admin_password' => 'admin',
 'setup_db_admin_user_name' => 'root',
 'setup_db_admin_password' => 'root',
 'setup_db_type' => 'mysql',
 'setup_license_key' => 'YOUR_SUBSCRIPTION_KEY',
 'setup_site_url' => 'http://localhost/~USER_NAME/sugarcrm/',
 'setup_system_name' => 'SugarCRM',
 'default_currency_iso4217' => 'USD',
 'default_currency_name' => 'US Dollars',
 'default_currency_significant_digits' => '2',
 'default_currency_symbol' => '$',
 'default_date_format' => 'Y-m-d',
 'default_time_format' => 'H:i',
 'default_decimal_seperator' => '.',
 'default_export_charset' => 'ISO-8859-1',
 'default_language' => 'en_us',
 'default_locale_name_format' => 's f l',
 'default_number_grouping_seperator' => ',',
 'export_delimiter' => ',',
 'setup_fts_type' => 'Elastic',
 'setup_fts_host' => 'localhost',
 'setup_fts_port' => '9200',

Reinstalling Sugar

Mess something up and need to start your Sugar installation over again?  You can always re-run the Sugar installer.  Modify config.php in your Sugar installation directory and change the following attribute from true to false.


'installer_locked' => false,

You can then re-run the installer by launching http://localhost/~USER_NAME/sugarcrm/install.php directly.

Optional Software

  • Postman: A REST client extension for Chrome this is very helpful for testing Sugar's REST API. The School of REST blog series is a great resource for learning to use Sugar's REST API.
  • Git: If you aren't already using a source code management system, it's time to start!  We suggest that you begin with Git.  See Development Methodology for best practices.

Learn to use Sugar

Now that you have Sugar setup on your local machine, you need to learn how to use it!  Check out Training & Certification.  Once you're comfortable with the basics of how to use Sugar, work through Developer Training.

About the Sample Data

The sample data you installed comes with several users as described in the table below:

Name Username Password Role
Jim Brennan  jim  jim  VP Sales
Sarah Smith  sarah  sarah  Sales Manager West 
Sally Bronsen  sally  sally  Senior Account Rep 
Will Westin  will  will  Sales Manager East 
Chris Olliver  chris chris  Senior Account Rep 
Max Jensen  max max  Account Rep 
Jane Fitzpatrick  jane  jane  Marketing Manager 
Charles James  charles  charles  Support Manager 
Regina Lazlow  regina  regina  Support Rep 
Jen Smith admin asdf Administrator

Last modified: 2020-08-10 17:33:23