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 -

          Changed recommendation to system package manager with links to distribution sites for latest if/when desired. Link to requirements page added to clarify what we test and support.

          Show
          David Christian Liedle (Inactive) added a comment - Changed recommendation to system package manager with links to distribution sites for latest if/when desired. Link to requirements page added to clarify what we test and support.
          Hide
          David Christian Liedle (Inactive) added a comment -

          As I go through the actual steps required (and/or useful) to configure a fresh server, I'm collecting those steps in a shell script here: https://github.com/DavidLiedle/ez/blob/master/ezplatform-install-debian-8-5.sh (Working on Debian first, others pending.) Obviously things like mosh and emacs aren't absolutely required, but it's my repo for my own testing and that's the environment I like best. Once I'm happy with the remaining steps I need to add and test, I'll overhaul the installation guide to match. Feel free to fork/change/extend anything in the script, or even just run it to get the same results.

          Show
          David Christian Liedle (Inactive) added a comment - As I go through the actual steps required (and/or useful) to configure a fresh server, I'm collecting those steps in a shell script here: https://github.com/DavidLiedle/ez/blob/master/ezplatform-install-debian-8-5.sh (Working on Debian first, others pending.) Obviously things like mosh and emacs aren't absolutely required, but it's my repo for my own testing and that's the environment I like best. Once I'm happy with the remaining steps I need to add and test, I'll overhaul the installation guide to match. Feel free to fork/change/extend anything in the script, or even just run it to get the same results.
          Hide
          Eduardo Fernandes (Inactive) added a comment -

          Hi [~david.liedle@ez.no],

          I forked your script and am changing it a little bit to make a few suggestions but I have a few doubts about about your version

          1) Why do you install php5-fpm if you already installed libapache2-mod-php?

          2) I see some "non standard" packages here not used by everyone, like mosh and emacs. That makes me think this is a script aimed to development machines, not servers. Am I right about it?

          Show
          Eduardo Fernandes (Inactive) added a comment - Hi [~david.liedle@ez.no] , I forked your script and am changing it a little bit to make a few suggestions but I have a few doubts about about your version 1) Why do you install php5-fpm if you already installed libapache2-mod-php ? 2) I see some "non standard" packages here not used by everyone, like mosh and emacs . That makes me think this is a script aimed to development machines, not servers. Am I right about it?
          Hide
          David Christian Liedle (Inactive) added a comment - - edited

          Hi [~eduardo.fernandes@ez.no],

          Cool! I'll take a look when you push your fork.

          1) That's a leftover from when I was taking the Nginx approach; good catch.

          2) Even more specific than dev/prod, the target user is simply me. What I'm doing right now is installing eZ Platform on droplets to iron out the steps in the Unix install page. This script automates the steps I was doing manually. I've added just enough documentation to explain what you see when I share it. I'm adding to it with some additional steps ( `php -d memory_limit=-1 \`which composer\` install `, `php -d memory_limit=-1 app/console ezplatform:install --env prod clean `, etc.) Jira isn't parsing the backticks as I expected, so imagine the parsed effect you'd expect if it had.

          If this looks useful to more than just me/us, we could explore the notion of dev/prod steps in the script. The steps I see for the Unix install guide would be dev-oriented, as that's logical within the context of "Getting Started". "Deploying" would be a logical header/page to continue the journey once a developer has gotten started.

          This isn't intended to kick-start an installer project; just putting my install steps where I can curl them and sharing in case it is useful to others.

          Show
          David Christian Liedle (Inactive) added a comment - - edited Hi [~eduardo.fernandes@ez.no] , Cool! I'll take a look when you push your fork. 1) That's a leftover from when I was taking the Nginx approach; good catch. 2) Even more specific than dev/prod, the target user is simply me. What I'm doing right now is installing eZ Platform on droplets to iron out the steps in the Unix install page. This script automates the steps I was doing manually. I've added just enough documentation to explain what you see when I share it. I'm adding to it with some additional steps ( `php -d memory_limit=-1 \`which composer\` install `, `php -d memory_limit=-1 app/console ezplatform:install --env prod clean `, etc.) Jira isn't parsing the backticks as I expected, so imagine the parsed effect you'd expect if it had. If this looks useful to more than just me/us, we could explore the notion of dev/prod steps in the script. The steps I see for the Unix install guide would be dev-oriented, as that's logical within the context of "Getting Started". "Deploying" would be a logical header/page to continue the journey once a developer has gotten started. This isn't intended to kick-start an installer project; just putting my install steps where I can curl them and sharing in case it is useful to others.
          Hide
          Eduardo Fernandes (Inactive) added a comment - - edited

          HI [~david.liedle@ez.no],

          The problem is that, for me, tweaking servers with things like {{ apt-get -qq -y upgrade && apt-get -qq -y dist-upgrade }} inside scripts is weird and most people won't want to use things like that. Even in personal workstations and development environments, I know a lot of people who have problems with updating.

          Things like emacs24-nox - which I can't say I like - and mosh - which I didn't know and am not sure if I will like - also worries me in this script, even for testing and development.

          But, something like this is helpful as an example for others and for me as a support member - since I must install eZ lots of times and not always can rely on things like vagrant - so I changed it a little bit to allow the user to choose what he wants to install without input.

          Check it here: https://github.com/psicofrenia/ez/blob/master/ezplatform-install.sh

          Not sure if this changes go towards what you initially wanted but I can always get back to the original

          Show
          Eduardo Fernandes (Inactive) added a comment - - edited HI [~david.liedle@ez.no] , The problem is that, for me, tweaking servers with things like {{ apt-get -qq -y upgrade && apt-get -qq -y dist-upgrade }} inside scripts is weird and most people won't want to use things like that. Even in personal workstations and development environments, I know a lot of people who have problems with updating. Things like emacs24-nox - which I can't say I like - and mosh - which I didn't know and am not sure if I will like - also worries me in this script, even for testing and development. But, something like this is helpful as an example for others and for me as a support member - since I must install eZ lots of times and not always can rely on things like vagrant - so I changed it a little bit to allow the user to choose what he wants to install without input. Check it here: https://github.com/psicofrenia/ez/blob/master/ezplatform-install.sh Not sure if this changes go towards what you initially wanted but I can always get back to the original
          Hide
          Eduardo Fernandes (Inactive) added a comment -

          Another things, I removed the php5-twig from the script... This package does not exist in my Ubuntu repositories (yes, I know this was originally for Debian) and I must add a check to install only if the package exist in the repositories

          Show
          Eduardo Fernandes (Inactive) added a comment - Another things, I removed the php5-twig from the script... This package does not exist in my Ubuntu repositories (yes, I know this was originally for Debian) and I must add a check to install only if the package exist in the repositories
          Hide
          Eduardo Fernandes (Inactive) added a comment - - edited

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

          I was rechecking the installation doc page. Imo, there's a misconception there. That is an eZ Public installation page, not a LAMP installation page.

          The problem is how and what is installed is very personal to sys admin and developers, and I don't think is a good idea to add such information on the page. So, topics like 2. Configure PHP could just go away and the page would be much better.

          Instead having

          date.timezone = "Europe/Warsaw"
          pdo_mysql.default_socket = /tmp/mysql.sock

          It would be much better to have:

          {qutote}

          Important! Remember eZ Platform needs the PHP timezone correctly set in the ini file.

          Instead having

          apt-get install php56-intl

          It would make more sense to have

          eZ Platform requires the following PHP packages: intl, imagemagick, etc..

          Instead having the vhosts file listed, just point to the usage of vhost.sh page.

          Show
          Eduardo Fernandes (Inactive) added a comment - - edited [~sarah.haim-lubczanski@ez.no] , [~david.liedle@ez.no] , I was rechecking the installation doc page. Imo, there's a misconception there. That is an eZ Public installation page, not a LAMP installation page. The problem is how and what is installed is very personal to sys admin and developers, and I don't think is a good idea to add such information on the page. So, topics like 2. Configure PHP could just go away and the page would be much better. Instead having date.timezone = "Europe/Warsaw" pdo_mysql.default_socket = /tmp/mysql.sock It would be much better to have: {qutote} Important! Remember eZ Platform needs the PHP timezone correctly set in the ini file. Instead having apt-get install php56-intl It would make more sense to have eZ Platform requires the following PHP packages: intl, imagemagick, etc.. Instead having the vhosts file listed, just point to the usage of vhost.sh page.
          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: