Docker Development Environment

Using Docker as a development environment to manage your Sugar development environment can offer several advantages, such as consistent setups across different machines, easy sharing of development environments, isolation of dependencies as well as compatibilities between Sugar versions and its Supported Platforms. Docker uses containerization to encapsulate Sugar and its dependencies in one single environment.

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: Docker setups are recommended for developers, but some customers would simply like to set up a copy of their Sugar instance for troubleshooting, 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.

Developer Office Hours

Sugar has hosted a session, December '23 - Office Hours - Sugar Development with Docker containers, worth watching.

Docker (Desktop) Setup

You will need to install Docker Desktop on your local machine. Docker Desktop contains everything you need to manage your images and containers as well as the docker-engine necessary to execute them in runtime. Docker Desktop is free for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open-source projects.

Step 1. Download or Check Out Sugar Application Files

Unzip the Sugar application files or check out your Sugar application code in 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 Docker shared folder. Using the same directory will cause conflicts because the Sugar instances will be using different copies of MySQL, Apache, Elasticsearch, etc.

Step 2. Use SugarDockerized

SugarDockerized is an open-source initiative designed to effortlessly manage the complete software stack required for running Sugar. This project leverages Docker Composer to encapsulate and isolate environments and their supported platforms per Sugar versions.

Installing SugarDockerized is as simple as cloning the repository, and starting the desired stack (which is maintained per Sugar major version).

Step 3. Install Sugar or Restore SugarCloud Backups

With your Docker environment up and running, you are now ready to install a new on-site Sugar instance or restore your SugarCloud backup and have it running locally. Please refer to the section below that best applies to your situation.

Installing an On-Site Sugar Instance

You can install an on-site Sugar instance using the SugarDockerized installation guide through installfromzip.sh. This command expects one single parameter, Sugar's installation package, when executed, this command triggers Sugar's Silent Install and completes the installation without any intervention by the user. Before you start the installation, you can customize license and demoData.

After installation, you can open Sugar's local URL (http://docker.local/sugar/) and enter your credentials to login. SugarDockerized does install demoData by default. You will be redirected to Sugar's license page to enter your Key.

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

This key can also be pre-configured in SugarDockerized's install_config.php which will install the key without the need to revalidate.

Restoring SugarCloud Backups

To restore your SugarCloud backup and have it running locally, use the SugarDockerized restore command through restorefromfile.sh. This command expects one single parameter, SugarCloud's backup tarball package. When executed, this command will clean up any previous installs, drop sugar databases (if exists), expand the tar, copy files to its proper places, restore database, recreate config_override.php with Docker containers data, recreate cache, and warm up services. When the command is done, you will have your instance ready.

Note: Your user data will be the same ones as in the cloud, not demo data.

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: