Preparations after unzip

Installing SugarCRM is generally easy, but if you don't want to just make everything writable by Apache, you may find it tricky, especially if you have problems setting up the system.

First of all, you want to get the code from SourceForget.net and extract it in the root directory of the website where you want to use it. I prefer to dedicate a sub-domain name such as crm.m2osw.com to make use of SugarCRM. That way I don't have to deal with other weird things of using this under a sub-directory.

Once in there, the user and group should be a user other than the Apache user (so not www-data if you're using Ubuntu.) That way the code is viewed as being read-only by the server. You could make it root:root if you'd like, but it is not required to go as far as using the root user for that.

Before you can install SugarOS, you'll have to allow it to modify a certain number of directories and files. There are the commands I run from the root directory of Sugar OS:

chown -R www-data:www-data cache config.php config_override.php \
                           custom modules sugarcrm.log upload

IMPORTANT: You will probably need to use sudo or su.

Change the 'www-data' to whatever your OS uses (maybe 'httpd').

Note that I did not have any problems with that scheme, however, if some of the read-only files still don't load, then you probably need to change their permissions to 644 (file) or 755 (dir). The following should do it (again I did not have to do that on my end so you probably don't need to run this command):

chmod -R r+go .

WARNING: using the '.' means that the current directory is also affected by the command.

IMPORTANT: You will probably need to use sudo or su.

Notice the -R to change the user/group information of all the files in those folders. Most folders have a file named index.html used to prevent preying eyes from seeing the contents of that folder. If that feature is turned off in Apache, you probably won't have a problem with it. Otherwise, you may want to revert those files back to a non-writable status, just in case.

You may have noticed the file named sugarcrm.log in the list. This is where log information are saved. It is important if you want to track what's happening. The system does not tell you anything if it is not capable of writing into that file...

Similarly, you want to create an install.log file so that way you can see what happens (does not happen) while installing the software. Quite unfortunate that SugarCRM does not (yet) have a log sub-directory...

touch install.log
chown www-data:www-data install.log

IMPORTANT: You will probably need to use sudo or su.

Note: you could create the install.log file first and add install.log to the previous line of code.

SugarCRM Upgrade Path

The SugarCRM upgrade feature is found in the Admin screen. Click on Admin, then search for Upgrade Wizard. Click on that link and you'll enter the wizard.

Assuming you made your installation read-only (I prefer to have it that way!) then you will need to create an upgradeWizard.log file and make it writable by your Apache server:

touch upgradeWizard.log
chown www-data:www-data upgradeWizard.log

IMPORTANT: You will probably need to use sudo or su.

Change 'www-data' to your Apache server user (maybe 'httpd'?)

Just like with the installation, file permissions are swarted (if you check before running the commands below you'll see a link saying: Show Files with Bad Permissions). Actually, in this case the system expects all the files to be writable since it will extract the .zip file over all of these. So you have to change the ownership to your Apache server as in:

cd /var/www/sugaros   # go to your SugarCRM installation
chown -R www-data:www-data .

WARNING: the '.' filename means the current directory will also be changed.

IMPORTANT: You will probably need to use sudo or su.

Change 'www-data' to your Apache server user (maybe 'httpd'?)

We will restore the read-only state after the upgrade is performed. This is done by changing everything back to your favorite user and then applying the chown as shown in the perparation section.

chown -R root:root .
chown -R www-data:www-data cache config.php config_override.php \
                           custom modules sugarcrm.log upload install.log

Strict Mode Generates TONS of errors?!

I run PHP in strict mode. There is no other way to make sure that your code is actually running as expected unless you have a complete and strong test suite (do you?!)

So... with SugarCRM that's a problem because it generates TONS of errors, like 50 a second or so. To avoid those errors, one can change the php value named error_reporting and set it to 0 (zero). That way you should not see any errors.

The remainder of the .htaccess (that should be in your root directory) is mentioned by SugarOS and it may change with time. This is the one from 6.5.17.

# Avoid all those strict warnings
php_value error_reporting 0
# my old install used 30719 or 22527 does not include deprecated notices.
# however, using 0 everything will "work" which is probably what you want.
# BEGIN SUGARCRM RESTRICTIONS
RedirectMatch 403 (?i).*\.log$
RedirectMatch 403 (?i)/+not_imported_.*\.txt
RedirectMatch 403 (?i)/+(soap|cache|xtemplate|data|examples|include|log4php|metadata|modules)/+.*\.(php|tpl)
RedirectMatch 403 (?i)/+emailmandelivery\.php
RedirectMatch 403 (?i)/+upload
RedirectMatch 403 (?i)/+custom/+blowfish
RedirectMatch 403 (?i)/+cache/+diagnostic
RedirectMatch 403 (?i)/+files\.md5$
# END SUGARCRM RESTRICTIONS

Note: I finally decided to change the error reporting value to zero (0) because when using things in the administration screen is really, really bad. Not just deprecated notices...

Cannot log in as root

As I was trying to install my instance, I kept getting errors about not being able to connect to mysql as root.

The system uses the root user to create the database and the SugarCRM user.

Access denied for user 'root'@'localhost' (using password: YES) (Mysql::Error)

That error occured because my password included a character that Browsers have to send as an entity. Namely, my password included < and it was sent as &lt;. That was then sent as is to the MySQL system. Of course, MySQL would not accept that stupid password and I would get that error.

I posted a potential fix on github, we'll see whether anyone takes the time to fix the problem...

The fix was to add html_entitity_decode() on line 197 of include/database/MysqliManager.php that then looks like this:

  $this->database = mysqli_connect($dbhost,$configOptions['db_user_name'],html_entity_decode($configOptions['db_password']),isset($configOptions['db_name'])?$configOptions['db_name']:'',$dbport);

This is not a complete fix, far from it, and it is not even the correct fix (the data in the $_POST needs to be fixed, not when used at the very end.

SugarCRM White Screen of Death (WSOD)

There are many different situations where SugarCRM will return a screen of death. For me, in most cases it has been because the software is not able to write to a given file. Now why the chown -R presented earlier would not work, I'm not too sure, but on my last installation I got two directories that still said root:root as the owner.

Re-running that chown command was enough for me to get rid of the WSOD.

In most cases you can easily find the error by turning on all the errors (although you'll get loads of them and most are notices about bad coding...) Look for entries that say "Fatal Error". In most cases, it would be a file copy or create that fails. Other reasons cannot be solved with the chown on its own...