Sugar Dockerized

This repository will help you deploy a Docker based development only full stack for Sugar, meeting all the platform requirements for a different set of platform combinations.

Donations

If you find this software useful, please consider supporting the work that went into it, with a monthly amount. Thank you!

<img src="https://www.paypalobjects.com/en_AU/i/btn/btn_donate_LG.gif">

Requirements

• linux platform - it can be a virtual machine
• docker
• docker-compose
• curl
• rsync
• zip
• tar
• git
• Sugar zip installer

Stacks available

There are few stacks available, with in itself multiple platform combinations. You can read more about the specific stacks on the links below:

• Sugar 12 - This stack is valid from version 12 for local developement also of Sugar Cloud only versions
• Sugar 11 - This stack is valid from version 11 for local developement also of Sugar Cloud only versions

You will find additional stacks within the stack directory of the project. For most stacks, there are both the pre-built version (eg on Sugar 9: ./stacks/sugar9/php73.yml) and a locally built version (eg on Sugar 9: ./stacks/sugar9/php73-local-build.yml). The locally built version will be built run-time, and therefore those stacks will let you specify additional changes you might require to the docker images provided. Local builds will take much longer to deploy than pre-built ones.

Types of stacks

There are mainly three types of stack:

• Single Apache web server - Initial development
• Single Apache web server with local run-time build - Initial development when you need to modify the stack to better suit specific needs
• An Apache load balancer with a cluster of two Apache web servers behind it - A more real-life environment to verify that everything works correctly

Stack components

There are multiple stack components as docker containers, that perform different duties. Not all the stack components might be used on a specific stack setup. Some of the stack components are listed below:

• Apache load balancer - Load balances requests between the cluster of Apache PHP web servers, round robin
• Apache PHP web server - Web server(s)
• MySQL database - Database
• Elasticsearch - Sugar search engine
• Redis - Two purposes: Sugar object caching service and PHP Session storage/sharing service
• Cron - Sugar background scheduler processing. Note that this is enabled immediately and it will run cron.php as soon as the file is available, and it will attempt to do so every 60 seconds since its last run. This container is used for any other CLI execution required during development
• Permission - Sets Sugar instance permissions correctly and then terminates

SugarDockerized installation

• The first step for everything to work smoothly, is to add on your computer's host file /etc/hosts the entry docker.local to point to your machine's ip (it might be 127.0.0.1 if running the stack locally, or the LAN static ip address of the VM running Docker. If using the Debian VirtualBox image provided at the bottom of this README, the ip address is 10.10.10.10)
• Clone the repository with git clone https://github.com/esimonetti/SugarDockerized.git sugardocker and enter sugardocker with cd sugardocker
• Choose the yml stack to run, within stacks

Starting and stopping the desired stack

Please leverage the utility script stack.sh that will help with automation of the most common stacks. The utility will also notify you if a new version of SugarDockerized is available.

Installation - How to get Sugar installed

For details about the hostnames and credentials of each of the infrastructure components, refer to Sugar Setup details.

Sugar installation via installable zip file

• The first step is to copy (cp/scp/rsync/filezilla etc) the compressed installable zip file into a known path within the Linux host running SugarDockerized
• Run the utility installfromzip.sh. Read more about installfromzip.sh

Sugar installation building from git source

• To be able to proceed further, you would need read permission access to Sugar's official git source control repository
• Clone the full git repository within your ./data/app/ directory so that the repository is located in ./data/app/Mango/
• Switch to the correct branch
• Run the utility build/build.sh. Read more about build/build.sh

Current version support

The main stacks work with Sugar version 9.0 and all its platform requirements. Additional stacks are aligned with the platform requirements of version 8.0, 7.9 and stacks for Sugar Cloud only versions for local development only.

System's details

Stack components hostnames and names

• Apache load balancer: sugar-lb
• Apache PHP web server; On single stack: sugar-web1 On cluster stack: sugar-web1 and sugar-web2
• MySQL database: sugar-mysql
• Elasticsearch: sugar-elasticsearch
• Redis: sugar-redis
• Cron: sugar-cron
• Permission: sugar-permissions

To verify all components hostnames just run docker ps when the stack is up and running.

Please note that on this setup, only the web server or the load balancer (if in single web server or cluster stack) and the database can be accessed externally. Everything else is only allowed within the stack components.

Core stack components

• Linux
• Apache
• MySQL
• PHP
• Redis
• Elasticsearch

Sugar Setup details

• Browser url: http://docker.local/sugar/ - Based on the host file entry defined above on the local machine
• MySQL hostname: sugar-mysql
  • MySQL db name: sugar
  • MySQL user: root
  • MySQL password: root
• Elasticsearch hostname: sugar-elasticsearch
• Redis hostname: sugar-redis

Apache additional information

Apache web servers have enabled:

• mod_headers
• mod_expires
• mod_deflate
• mod_rewrite

PHP additional information

Apache web servers have PHP with enabled:

• Zend OPcache - Configured for Sugar with the assumption the files will be located within the correct path
• XHProf and Tideways profilers
• Xdebug is installed but it is not enabled by default (due to its performance impact). For PHP 5.6 images and all cron images if there is the need to enable it, you would have to uncomment the configuration option on the PHP Dockerfile of choice, and leverage the stack configuration with local build. For other case see xdebug.sh.

  • If you use an IDE such as PHPStorm, you can setup DBGp Proxy under the menus Preference -> Language & Framework -> PHP -> Debug -> DBGp Proxy. Example settings are available in the screenshot below:

    <img width="1026" alt="PHPStorm xdebug settings" src="https://user-images.githubusercontent.com/361254/38972661-d48661f6-4356-11e8-9245-ad598239fe94.png">

    • Debug with Xdebug Helper

      If you use Chrome as a browser, you can install the extension Xdebug helper. When ready to debug, click the debug button on the Xdebug helper, and click on "Start listening for PHP Debug Connections" within PHPStorm

      <img width="146" alt="xdebughelper" src="https://user-images.githubusercontent.com/361254/43093912-5a7a3bf2-8e66-11e8-9c11-811316d8f2ee.png"> <img width="50" alt="Start listening for PHP Debug Connections" src="https://user-images.githubusercontent.com/361254/43093985-8d4aa724-8e66-11e8-946c-5ccc83b62560.png">

    • Debug with Postman

      It is possible to debug a specific API endpoint through Postman leveraging a similar approach. In this example, we are going to debug the login authentication api endpoint rest/v11_1/oauth2/token. The first step is to add the cookie "XDEBUG_SESSION" in Postman. The same cookie is set through the Xdebug helper, and the keyword is referenced on the PHPstorm settings and on Xdebug PHP server side settings as well. See screenshots below:

      <img width="948" alt="Debug with Postman" src="https://user-images.githubusercontent.com/361254/43094521-0cf97058-8e68-11e8-8fc3-303c513dc1e9.png"> <img width="679" alt="Postman cookie setting for remote debug" src="https://user-images.githubusercontent.com/361254/43094713-9190640c-8e68-11e8-95e0-11b866e452d4.png">

Session storage is completed leveraging the Redis container.

Elasticsearch additional information

If you notice that your Elasticsearch container is not running (check with docker ps), it might be required to tweak your Linux host settings. To be able to run Elasticsearch version 5 and above, it is needed an increase of the maximum mapped memory a process can have. To complete this change permanently run:

echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

Alternatively the limit can be increased runtime wit