Vagrant Development Environment

Overview

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 SugarCloud Sandbox or, for on-site instances, Cloning a Sugar Instance for Testing.

Vagrant Setup

You will need to install Vagrant and Virtualbox on your local machine. Both of these applications are free to use.

Step 1. Download or Check Out 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.

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.

If you are using Virtualbox, then run the following commands.

                          cd <SUGAR_DIRECTORY>
vagrant init <BOX_NAME>
vagrant up --provider virtualbox

Note: Your 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.

./config_si.php

                          <?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',
);

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.

./config.php

                          'installer_locked'=> false,

You can then re-run the installer by launching http://localhost:8080/sugar/install.php directly.

Learning to Use Sugar

Now that you have Sugar set up 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 generated comes with several users as described in the table below:

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.

Some changes do not require the full Quick Repair and Rebuild to be run. Incremental JavaScript changes to Sidecar components can usually be propagated by deleting the /cache/javascript/components_*.js files. New PHP files and classes can often be propagated by deleting ./cache/class_map.php (and ./cache/file_map.php if this exists).

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
sudo su
cd /var/log/apache2
cat error.log

Vagrant was unable to mount VirtualBox shared folders?

If you are bringing up your vagrant box and getting the follow error, most likely your vagrant guest plugin is either missing or out-dated.:

                          ==> default: Machine booted and ready!
==> default: Checking for guest additions in VM...
  default: The guest additions on this VM do not match the installed version of
  default: VirtualBox! In most cases this is fine, but in rare cases it can
  default: prevent things such as shared folders from working properly. If you see
  default: shared folder errors, please make sure the guest additions within the
  default: virtual machine match the version of VirtualBox you have installed on
  default: your host and reload your VM.
  default:
  default: Guest Additions Version: 5.2.8_KernelUbuntu r120774
  default: VirtualBox Version: 6.1
==> default: Mounting shared folders...
  default: /vagrant => /Users/mmarum-mac2/temp/SugarEnt-Full-12.0.0
Vagrant was unable to mount VirtualBox shared folders. This is usually
because the filesystem "vboxsf" is not available. This filesystem is
made available via the VirtualBox Guest Additions and kernel module.
Please verify that these guest additions are properly installed in the
guest. This is not a bug in Vagrant and is usually caused by a faulty
Vagrant box. For context, the command attempted was:
mount -t vboxsf -o uid=1000,gid=1000,_netdev vagrant /vagrant
The error output from the command was:
mount: /vagrant: wrong fs type, bad option, bad superblock on vagrant, missing codepage or helper program, or other error.

Open a shell and run the following commands to fix this:

                          # if plugin is missin, install it
vagrant plugin install vagrant-vbguest
#if plugin is out-dated, update it
vagrant plugin update vagrant-vbguest