Vagrant Development Environment
Using Vagrant to manage your Sugar development environment is a very easy way to get started with Sugar development without having to set up a local web server, PHP, etc. If you follow the directions below, you will be up and running on Sugar in less than 20 minutes. Vagrant is available on Windows, OS X, and common Linux distributions.
Access to Sugar's source code is available via Download Manager once you become a Sugar Partner or a Sugar Customer. This is also where you will get the subscription keys that will allow you to run Sugar to test your changes. Keep in mind that the instructions here are similar to what you can find in the official Sugar Installation and Upgrade Guide.
Note: Vagrant setups are recommended for developers, but some customers would simply like to set up a copy of their Sugar instance for testing or training purposes. For these scenarios, we recommend setting up a Sugar Cloud Sandbox or, for on-site instances, Cloning a Sugar Instance for Testing.
Step 1. Download or Checkout Sugar application files
Unzip the Sugar application files or check out your Sugar application code into a local development directory.
If you have a local web server running with Sugar already, do not use the same directory for your local server setup and your Vagrant setup. Using the same directory will cause conflicts because the Sugar instances will be using different copies of MySQL, Apache, Elasticsearch, etc.
Note: Users of macOS High Sierra may experience issues with the file system. This is a known issue reported in https://github.com/hashicorp/vagrant/issues/8788. Upgrading to macOS High Sierra 10.13.2 Beta 2 or higher will likely resolve the issue.
Step 2. Launch Vagrant
A few Vagrant boxes are currently available. Use the table below to determine the box that is supported by the Sugar version that you downloaded in Step 1.
|Box Name||Compatible Sugar Versions||Installed Software Stack||Notes|
|mmarum/sugar7-php56||7.8.x||Apache 2.4, PHP 5.6, MySQL 5.6, Elasticsearch 1.4||Based on Ubuntu 14.04
|sugarcrm/php71||7.9.x||Apache 2.4, PHP 7.1, MySQL 5.6, Elasticsearch 1.7||Based on Ubuntu 16.04
|sugarcrm/php71es54||7.10.x - 7.11.x (Sugar cloud only)||Apache 2.4, PHP 7.1, MySQL 5.7, Elasticsearch 5.4||Based on Ubuntu 16.04
|sugarcrm/php71es56||8.0.x, 8.1.x (Sugar cloud only)||Apache 2.4, PHP 7.1, MySQL 5.7, Elasticsearch 5.6||Based on Ubuntu 16.04
If you are using Virtualbox, then run the following commands.
cd <SUGAR_DIRECTORY> vagrant init <BOX_NAME> vagrant up --provider virtualbox
SUGAR_DIRECTORY is the directory that contains all of the Sugar files (like index.php). If you created a parent directory that contains the directory of Sugar files, be sure to use the child directory as your
SUGAR_DIRECTORY in the commands above.
Vagrant will download a box automatically and launch it. By default, this vagrant box is configured to use 3GB of memory. We do not recommend going smaller than 2GB of memory for this box because of performance. This box will also forward some ports for your convenience that need to be available on the host system. It forwards port 80 to 8080 for the web server, 9200 to 9292 for Elasticsearch, and 3306 to 3336 for MySQL database on your host system. Forwarding Elasticsearch and MySQL ports is not required for the box to work properly but are available for debugging purposes. You can adjust any of these settings by changing the values in your local Vagrantfile as necessary.
Step 3. Installation & Sugar Time!
At this point, you have Apache, Elasticsearch & MySQL all running within your Vagrant box. This means you are ready to install Sugar.
Navigate to http://localhost:8080/sugar/ in your web browser.
Follow the steps within to set up 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 and Password, you should use root.
- 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 the 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 set up during installation to log in.
You can run
vagrant suspend to suspend your box. See https://www.vagrantup.com/docs/cli/ for more options for interacting with your box.
Silent Installation Config
Throughout development, you may find yourself wanting to start over with a fresh installation of Sugar. To expedite 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.
<?php $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:8080/sugar/', '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', );
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
You can then re-run the installer by launching http://localhost:8080/sugar/install.php directly.
Learn to use Sugar
Now that you have Sugar set up on your local machine, you need to learn how to use it! Check out Sugar University's New Sugar User Orientation. Once you're comfortable with the basics of how to use Sugar, work through Sugar University's Developer Training.
About the Sample Data
The sample data you generated comes with several users as described in the table below:
|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|
Frequently Asked Questions
Quick Repair is too slow! What can I do?
If you are using the Virtualbox provided, you may find certain operations like Quick Repair and Rebuild taking a minute or sometimes more. This is due to poor file I/O performance that is the result of Vagrant's default use of Virtualbox Shared Folder to sync the contents of the Sugar directory with the box. Switching to a different Vagrant synced folder implementation will greatly improve performance but requires some additional setup that is operating system specific. If you are running OSX or Linux, you can follow Vagrant's NFS synced folder set up instructions. If you are running Windows, you can follow Vagrant's RSync synced folder or Vagrant's SMB synced folder set up instructions.
/cache/components_*.js files. New PHP files and classes can often be propagated by deleting
Adding extensions or changing of Sugar metadata requires a Quick Repair and Rebuild. For example, if you add a vardefs change that causes DB changes, then you'll need to run a Quick Repair to ensure the changes take effect. Or, if you add a Sidecar extension, you will need to run a Quick Repair. When in doubt, run Quick Repair to ensure everything is rebuilt. If Quick Repair does not allow your change to appear, something is wrong with your customization.
How can I debug 500 errors?
If you are accessing your Sugar instance in a browser and seeing 500 errors, you can begin debugging by looking at the error log. Open a shell and run the following commands:
cd <SUGAR_DIRECTORY> vagrant ssh cd /var/log/apache2 cat error.log
Last modified: 2018-07-12 13:57:54