Numerous issues with installation instructions

[edqallen]

Issue

There are multiple omissions and assumptions in the installation instructions located at https://docs.suitecrm.com/admin/installation-guide/downloading-installing/ as well as a few shortcomings in the installer itself. These issues should probably be in several different tickets, but I leave that to the development/management team to decide.

Expected Behavior

Following the installation instructions should result in a working system.

Actual Behavior

Following the installation instructions results in a non-working system until corrections are made.

Possible Fix

Update the installation instructions to include all relevant details in line with the following lists.

First, these are additional PHP or Apache modules required for SuiteCRM to operate that are not mentioned in the requirements document or installation instructions.

• The PHP Session module.
• A database module is needed but no list of compatible modules is given. For example, with a MySQL server, should the mysql, mysqli or the pdo_mysql module be installed?
• "Sprite support" is listed but not explained and there is no PHP "sprite" module. The module you need for sprite support is GD.
• The Apache mod_redirect module.

Next, some pain points during the web based install after the above are addressed:

• During installation if the .htaccess file is not writable by the webserver, the error is not nicely formatted the way the config.php module is, making copy/paste impossible.
• Overrides must be allowed in the main apache config for the .htaccess file to function.
• If the config.php file cannot be created during installation, the contents are provided for you to copy & paste before you continue, but no instructions no how to continue after creating the file are provided.
• When you opt to populate the database with demo data, it says the process may take some time, but no progress indication of any kind is given, not even a simple statement saying that the demo data load is complete.

Steps to Reproduce

1. Create a blank standalone machine or VM running your OS of choice. I used FreeBSD 12.2.
2. Follow the instructions at https://docs.suitecrm.com/admin/installation-guide/downloading-installing/

Context

Trial and error of post-installation errors until the system became operational was required.

Your Environment

• SuiteCRM Version used: 7.11.18
• Environment name and version (e.g. MySQL, PHP 7): MySQL, PHP 7
• Operating System and version (e.g Ubuntu 16.04): FreeBSD 12.2

[pgorod]

Shouldn't this be an Issue on the Docs Github instead?

https://github.com/salesagility/SuiteDocs/issues

or better yet, a PR with proposed changes to the Docs.

I agree a lot (a LOT) can be improved in those instructions, but in my experience it's not easy to add detail in all matters of Linux administration that are possible to be faced. And people's experience varies greatly, so what is a good help for some newbies, is waaay too much detail for a seasoned admin.

A possible nice way to do it is to keep the basic instructions simple and straight-forward but have a handful of "Technical blog" post articles detailing how to install in specific distros (say Ubuntu 20.04), or detailing how to overcome .htaccess problems etc.