Uploaded image for project: 'eZ Publish / Platform'
  1. eZ Publish / Platform
  2. EZP-25890

Documentation: UNIX-based installation Guide must be reviewed

    Details

      Description

      There are some inconsistencies on the Installation Guide for Unix-based Systems documentation page.

      MySQL install section does not make sense

      Download from the official MySQL webpage is strongly recommended.

      Why we strongly recommend customers to download MySQL from their website instead using the standard packages of their distributions with
      which our software was tested?

      Besides the testing, it's important to remember that we must provide support and reproduce customer bugs and as closer their environment is to testing and support environments, the better.

      PHP set up incomplete

      This step requires the modification of two files: Apache2 configuration file and php.ini.
      These files can be edited using a terminal editor like vi or nano, or a simple text editor such as TextEdit or Atom.

      The steps described in this howto to install php is incomplete and won't make sense to the supported platforms - maybe in MacOs only - and shouldn't be here.

      The paths are non standard

      According to the Requirements & System Configuration page, the recommended setups should be Debian, Ubuntu or RHEL / CentOS.

      The paths on the page are not the ones used in neither of these systems and should be fixed.

      sudo vi /private/etc/apache2/httpd.conf
      sudo vi /private/etc/apache2/users/ez1.lh.conf

      • In the first case, the path should probably be /etc/apache2/apache2.conf in Debian and /etc/httpd/httpd.conf in CentOS.
      • In the second one, /etc/apache2/apache2.conf in Debian and /etc/httpd/conf.d in CentOS.

      MacOS is not a supported platform and should not be used in documentation

      Apache setup

      b. Uncomment and modify the following lines:

      LoadModule vhost_alias_module libexec/apache2/mod_vhost_alias.so
      LoadModule rewrite_module libexec/apache2/mod_rewrite.so

      This does not make sense since Debian, for example, uses a2enmod to enable modules. But the main reason is we shouldn't explain how to enable modules, we should just list them as required on the Requirements page.

      Hosts file configuration

      This step is allows you to use ez1.lh as an address to access running Platform from a web browser. You can substitute the address with the address you intend to use to access your installation (remember to change it in all other command on this page as well):

      This is something only makes sense in a development environment. It should be removed from the official documentation.

      Composer should not be installed this way

      mv composer.phar /usr/local/bin/composer

      I remember some time ago we - engineering - talked about having the documentation with a composer alias or the full command php -d memory_limit=-1 composer.phar and the decision was stay with the full command to have a safe standard. This rule should be kept here and in the documentation.

      Install additional requirements for eZ Platform

      cd /usr/lib/php
      sudo php install-pear-nozlib.phar

      • If the steps described here are mandatory, why they are not described in the INSTALL.md file? I think they are not.
      • The steps does not explain how to obtain the install-pear-nozlib.phar file and so they won't work.

      apt-get install icu4c
      sudo pecl install intl

      • Again, we shouldn't explain how to install packages but list them as required on the Requirements. Besides, I think icu4c won't even exist in Debian and CentOs.

      Install eZ Platform

      git clone https://github.com/ezsystems/ezplatform.git

      The steps listed here are very different from the ones described in the INSTALL.md file what is very confusing, specially for customers since the Manual Installation Guides page instructs them to download the software from share.ez.no/downloads/downloads.

      Modify virtual host file based on dev environment

      • The steps listed here should follow the lead on Apache 2.2 / 2.4 configuration.
      • Listing a virtual host file here may result in compatibility and maintenance problems. Instead, we should link it to the vhost.template on Github.

      Install required dependencies using Composer

      composer install

      Again the full form should be used.

      Invalid permissions

      sudo chmod +a "_www allow delete,write,append,file_inherit,directory_inherit" app/{cache,logs,config} web

      Afaik, these are MacOS only - see Mac OS Man page - and shouldn't be here.

      Optional steps

      Some of these steps does not make sense to Debian or CentOS.

        Issue Links

          Activity

          Hide
          David Christian Liedle (Inactive) added a comment - - edited

          [~eduardo.fernandes@ez.no]: I would like to keep full detail in our guides, allowing beginners, intermediate, and advanced developers (who may have forgotten a couple steps pertaining to installation details) to find everything they need to go from nothing-to-something with eZ. I'm open to discussing how we organize that, but I don't want to make assumptions about our audience nor send them elsewhere for information on steps that are required to achieve success.

          Show
          David Christian Liedle (Inactive) added a comment - - edited [~eduardo.fernandes@ez.no] : I would like to keep full detail in our guides, allowing beginners, intermediate, and advanced developers (who may have forgotten a couple steps pertaining to installation details) to find everything they need to go from nothing-to-something with eZ. I'm open to discussing how we organize that, but I don't want to make assumptions about our audience nor send them elsewhere for information on steps that are required to achieve success.
          Hide
          Sarah Haïm-Lubczanski (Inactive) added a comment -

          [~david.liedle@ez.no] We can have 2 flavors :
          1- the Unix installation page, with a reminder of the necessary steps (database, server config, PHP config, etc.)
          2- a Cookbook recipe "Set up your eZ Platform instance quick and easy" for the Beginners with command lines instructions, step by step

          What do you think about it ?

          Show
          Sarah Haïm-Lubczanski (Inactive) added a comment - [~david.liedle@ez.no] We can have 2 flavors : 1- the Unix installation page, with a reminder of the necessary steps (database, server config, PHP config, etc.) 2- a Cookbook recipe "Set up your eZ Platform instance quick and easy" for the Beginners with command lines instructions, step by step What do you think about it ?
          Hide
          Eduardo Fernandes (Inactive) added a comment -

          [~david.liedle@ez.no] & [~sarah.haim-lubczanski@ez.no],

          Hi guys,

          Actually I am all for the customer and think we should be as specific as possible, not assuming somebody is an advanced developer or a sys admin... But I also think it's no the best approach to mix the application installation with the system installation. That's mainly because there are a lot of ways to configure and install the system.

          For example, we support Nginx & Apache, MySQL & MariaDB and, by doing a install page in the way it is, we will be "choosing" one of them and leave the other out. And as we point installation mechanics, we will assume for example the user is going to install the server with the apache user or setting up permissions because he installed everything with root but there are a lot of ways and when we mix system with application, we will be choosing the one we like more.

          That said, I think Sarah suggested a good approach. The install documentation page could be an installation page with the system requirements generically described, so it would fit an system environment. Instead specifying apt-get install php5-intl it would, imo, be better to explain that You must install the PHP Intl package since it's a requirement.

          Following that, it would be nice to make a script - yours is a great example, David - or have a github howto specific for a LAMP installation. There, all the steps to install Apache, MySQL and PHP.

          But, of course, this is just my 2 cents

          Show
          Eduardo Fernandes (Inactive) added a comment - [~david.liedle@ez.no] & [~sarah.haim-lubczanski@ez.no] , Hi guys, Actually I am all for the customer and think we should be as specific as possible, not assuming somebody is an advanced developer or a sys admin... But I also think it's no the best approach to mix the application installation with the system installation. That's mainly because there are a lot of ways to configure and install the system. For example, we support Nginx & Apache, MySQL & MariaDB and, by doing a install page in the way it is, we will be "choosing" one of them and leave the other out. And as we point installation mechanics, we will assume for example the user is going to install the server with the apache user or setting up permissions because he installed everything with root but there are a lot of ways and when we mix system with application, we will be choosing the one we like more. That said, I think Sarah suggested a good approach. The install documentation page could be an installation page with the system requirements generically described, so it would fit an system environment. Instead specifying apt-get install php5-intl it would, imo, be better to explain that You must install the PHP Intl package since it's a requirement. Following that, it would be nice to make a script - yours is a great example, David - or have a github howto specific for a LAMP installation. There, all the steps to install Apache, MySQL and PHP. But, of course, this is just my 2 cents
          Hide
          Sarah Haïm-Lubczanski (Inactive) added a comment -

          Somehow sync with the INSTALL.md file can be useful : https://github.com/ezsystems/ezplatform/blob/master/INSTALL.md

          Show
          Sarah Haïm-Lubczanski (Inactive) added a comment - Somehow sync with the INSTALL.md file can be useful : https://github.com/ezsystems/ezplatform/blob/master/INSTALL.md
          Hide
          Rui Silva (Inactive) added a comment -

          QA has reviewed the steps thoroughly as well and it seems all is ok now: the system paths match unix-based systems, the step 3 installation procedure now applies correctly, and I'm also for having this document oriented towards an apache setup, and spanning a different page for other setups such as nginx. However that should be turned into another story other than this in my belief, so for now I'm closing this jira as nothing seems to need to be done any more on this document.
          Validated by QA.

          Show
          Rui Silva (Inactive) added a comment - QA has reviewed the steps thoroughly as well and it seems all is ok now: the system paths match unix-based systems, the step 3 installation procedure now applies correctly, and I'm also for having this document oriented towards an apache setup, and spanning a different page for other setups such as nginx. However that should be turned into another story other than this in my belief, so for now I'm closing this jira as nothing seems to need to be done any more on this document. Validated by QA.

            People

            • Assignee:
              Unassigned
              Reporter:
              Eduardo Fernandes (Inactive)
            • Votes:
              1 Vote for this issue
              Watchers:
              7 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: