Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Skip to end of metadata
Go to start of metadata
The requirements for doing a normal installation must be met, read the "Requirements for doing a normal installation" section first!

Installing eZ Platform?

This page covers install of eZ Publish 5.x (including community versions like v2014.11), for eZ Platform see INSTALL.md bundled with the installation.

 

This section will guide you through the following steps:

Follow the status labels for the right version : 5.X 5.0 5.1 5.2  >= 5.3 / 2014.05

Setting up a database 5.X

A database must be created before running the setup wizard. The following text explains how to set up a database using either MySQL or PostgreSQL.

MySQL

  1. Log in as the root user (or any other MySQL user that has the CREATE, CREATE USER and GRANT OPTION privileges):

    Note that if MySQL is installed on the same server, the "--host" parameter can be omitted. If the "--port" parameter is omitted, the default port for MySQL traffic will be used (port 3306).

    The MySQL client should display a "mysql>" prompt.

  2. Create a new database:

    mysql> CREATE DATABASE <database> CHARACTER SET utf8;
  3. Grant access permissions:

    mysql> GRANT ALL ON <database>.* TO <user>@<ezp_host> IDENTIFIED BY '<password>';

    Note that if the specified user account does not exist, it will be created.

    ReferenceDescription
    <mysql_host>The hostname of the MySQL database server.
    <port>The port number that will be used to connect to the MySQL database server.
    <mysql_user>The MySQL user (if no user is set up, use "root").
    <mysql_password>The password that belongs to the <mysql_user>.
    <database>The name of the database, for example "my_new_database".
    <user>The username that will be used to access the database.
    <ezp_host>The hostname of the server on which eZ Publish will be running. (may be "localhost" if MySQL is installed on the same server).
    <password>The password you wish to set in order to limit access to the database.

PostgreSQL

  1. Log in as the postgres user (or any other PostgreSQL user that has sufficient privileges to create roles and databases):

    $ psql -h <psql_host> -p <port> -U <psql_user> -W

    Note that if PostgreSQL is installed on the same server, the "-h" parameter can be omitted. If the "-p" parameter is omitted, the default port for PostgreSQL traffic will be used (in most cases, port 5432).

    The PostgreSQL client will ask you to specify the password that belongs to the <psql_user>. If the password is correct, the client should display a "<psql_user>=#" prompt.

  2. Create a new database:

    postgres=# CREATE DATABASE <database> ENCODING='utf8';
  3. Create a new user:

    postgres=# CREATE USER <user> PASSWORD '<password>';
  4. Grant access permissions:

    postgres=# GRANT ALL PRIVILEGES ON DATABASE <database> TO <user>;

     

    Import the "pgcrypto" module into the new database:

    postgres=# \c <database>
    <database>=# \i '<path_to_pgcrypto>'
    ReferenceDescription
    <psql_host>The hostname of the PostgreSQL database server.
    <port>The port number that will be used to connect to the PostgreSQL database server.
    <psql_user>The PostgreSQL user (if no user is set up, use "postgresql").
    <database>The name of the database, for example "my_new_database".
    <user>The username that will be used to access the database.
    <password>The password you wish to set in order to limit access to the database.
    <path_to_pgcrypto>The path to the "pgcrypto.sql" file, for example "/usr/share/pgsql/contrib/pgcrypto.sql".

    Note for version 9.1+ of PostgreSQL users:
    The following changes might be necessary for these users:
    postgres=# \c <database>
    <database>=# CREATE EXTENSION pgcrypto;

Downloading eZ Publish 5.X

The latest community version of eZ Publish can be downloaded from http://share.ez.no/downloads

Enterprise version is available in your support portal or via partner portal.

Unpacking eZ Publish 5.X

Use your favorite tool to unpack the downloaded eZ Publish distribution to a web-served directory (a directory that is reachable using a web browser), or in case of virtual host mode it can be any folder.
The following example shows how to do this using the tar utility (to unpack a tar.gz file, assuming that the "tar" and the "gzip" utilities are installed on the system):

$ tar zxvf ezpublish-<version_number>-gpl.tar.gz -C <web_served_directory>
ReferenceDescription
<version_number>The version number of eZ Publish that was downloaded.
<web_served_directory>Full path to a directory that is served by the web server. This can be the path to the document root of the web server, or a personal web-directory (usually called "public_html" or "www", and located inside a user's home directory).

 

The extraction utility will unpack eZ Publish into a sub-directory called "ezpublish-<version_number>". Feel free to rename this directory to something more meaningful, for example "my_site".

Setting up folder permission 5.X

Important

In the 3 first folder permission setup options, always ensure to run application scripts and the web server with the appropriate UNIX user (must be same as you setup rights for below).

As for Apache you can control which user to use in your Apache configuration. Using PHP-FPM or SuExec module, you can even specify a user per virtual host.

Several cache, log and config folders must be writable both by the web server and the command line user, use one of the following alternatives to do this:

  • Using ACL on a system that supports chmod +a
    These shell commands will give proper permission to the web server and command line users.

    5.3 / 2014.05 and higher: >= 5.3 / 2014.05

        $ cd /<ezp5-root>/
        $ sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" \
          ezpublish/{cache,logs,config,sessions} ezpublish_legacy/{design,extension,settings,var} web
        $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" \
          ezpublish/{cache,logs,config,sessions} ezpublish_legacy/{design,extension,settings,var} web

    5.0, 5.1 and 5.2: 5.0 5.1 5.2

        $ cd /<ezp5-root>/
        $ sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" \
          ezpublish/{cache,logs,config} ezpublish_legacy/{design,extension,settings,var} web
        $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" \
          ezpublish/{cache,logs,config} ezpublish_legacy/{design,extension,settings,var} web


  • Using ACL on a system that does not support chmod +a
    Some systems don't support chmod +a, but do support another utility called setfacl. You may need to enable ACL support on your partition and install setfacl before using it (as is the case with Ubuntu).
    5.3 / 2014.05 and higher: >= 5.3 / 2014.05

        $ cd /<ezp5-root>/
        $ sudo setfacl -R -m u:www-data:rwx -m u:www-data:rwx \
          ezpublish/{cache,logs,config,sessions} ezpublish_legacy/{design,extension,settings,var} web
        $ sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx \
          ezpublish/{cache,logs,config,sessions} ezpublish_legacy/{design,extension,settings,var} web

    5.0, 5.1 and 5.2: 5.0 5.1 5.2

        $ cd /<ezp5-root>/
        $ sudo setfacl -R -m u:www-data:rwx -m u:www-data:rwx \
          ezpublish/{cache,logs,config} ezpublish_legacy/{design,extension,settings,var} web
        $ sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx \
          ezpublish/{cache,logs,config} ezpublish_legacy/{design,extension,settings,var} web
  • Using chown on systems that don't support ACL
    Some systems don't support ACL at all. You will either need to set your web server's user as the owner of the required directories.
    5.3 / 2014.05 and higher: >= 5.3 / 2014.05

        $ cd /<ezp5-root>/
        $ sudo chown -R www-data:www-data ezpublish/{cache,logs,config,sessions} ezpublish_legacy/{design,extension,settings,var} web
        $ sudo find {ezpublish/{cache,logs,config,sessions},ezpublish_legacy/{design,extension,settings,var},web} -type d | xargs sudo chmod -R 775
        $ sudo find {ezpublish/{cache,logs,config,sessions},ezpublish_legacy/{design,extension,settings,var},web} -type f | xargs sudo chmod -R 664

    5.0, 5.1 and 5.2: 5.0 5.1 5.2

        $ cd /<ezp5-root>/
        $ sudo chown -R www-data:www-data ezpublish/{cache,logs,config} ezpublish_legacy/{design,extension,settings,var} web
        $ sudo find {ezpublish/{cache,logs,config},ezpublish_legacy/{design,extension,settings,var},web} -type d | xargs sudo chmod -R 775
        $ sudo find {ezpublish/{cache,logs,config},ezpublish_legacy/{design,extension,settings,var},web} -type f | xargs sudo chmod -R 664
  • Using chmod
    If you can't use ACL and aren't allowed to change owner, you can use chmod, making the files writable by everybody. Note that this method really isn't recommended as it allows any user to do anything.
    5.3 / 2014.05 and higher: >= 5.3 / 2014.05

        $ cd /<ezp5-root>/
        $ sudo find {ezpublish/{cache,logs,config,sessions},ezpublish_legacy/{design,extension,settings,var},web} -type d | xargs sudo chmod -R 777
        $ sudo find {ezpublish/{cache,logs,config,sessions},ezpublish_legacy/{design,extension,settings,var},web} -type f | xargs sudo chmod -R 666

    5.0, 5.1 and 5.2: 5.0 5.1 5.2

        $ cd /<ezp5-root>/
        $ sudo find {ezpublish/{cache,logs,config},ezpublish_legacy/{design,extension,settings,var},web} -type d | xargs sudo chmod -R 777
        $ sudo find {ezpublish/{cache,logs,config},ezpublish_legacy/{design,extension,settings,var},web} -type f | xargs sudo chmod -R 666

Install Composer >=5.3 / 2014.05

If you use a version control system, take care of versioning the composer.lock file.

Install Composer by running one of the following command from you eZ Publish root folder :

If you have curl installed:

curl -sS https://getcomposer.org/installer | php

If you don't have curl installed:

php -r "eval('?>'.file_get_contents('https://getcomposer.org/installer'));"


When Composer is installed, run composer update to get latest versions of packages before you continue with installation.

Learn more on how to keep system further up to date  Using Composer

Pure legacy setup

If you are running a pure legacy setup, then commands such as composer install should be done within the legacy root folder, this will take care about installing latest versions of Zeta Components and defined eZ Publish (legacy) extension dependencies.

Optional : Link assets 

The download file should already have generated these assets for you as of 5.2 / 2013.07 during composer install, but in case file has been extracted on Windows, make sure to run these commands.

To be able to run eZ Publish 5 correctly, assets need to be exposed in the public "web" folder, this is automatically done for you when you install / update vendors via composer which you did a few steps up. However during development you will need to execute these (especially last one) to get assets to be updated in prod environment, so they are kept here for reference.

The following commands will first symlink eZ Publish 5 assets in "Bundles" and the second will symlink assets (design files like images, scripts and css, and files in var folder)  from eZ Publish Legacy

cd /<ezp5-root>
php ezpublish/console assets:install --relative --symlink web
php ezpublish/console ezpublish:legacy:assets_install --relative --symlink web
php ezpublish/console assetic:dump --env=prod web

Note: In both cases "web" is the default folder and can be skipped from the command. For symlinks on the first two commands you can either use --relative, --symlink, or none to get the command to copy assets. However make sure to also update "symfony-assets-install" in composer.json if you prefer something else then --relative which is the default.

Further information about alternative options is available with -h on each command, just like it is with the console itself using "php ezpublish/console -h".

Warning regarding APC usercache

If you are planning to use APC usercache for eZ Publish Persistence cache, please be sure to check the available notes here, before entering the setup wizard chapter.

Initiating the setup wizard 5.X

The setup wizard can be started using a web browser immediately after the previous steps (described in this section) are completed. It will be automatically run the first time someone tries to access/browse the "/ezsetup" url.

 

6 Comments

  1. FYI for dev environment assets should be deployed with:

    php ezpublish/console assetic:dump --env=dev 

     

     

     

  2. Afaik that is only the case if your installing using dev environment and intended to use that after install, a bit of improvement potential on the whole assetic/assets handling, this is tracked within the Symfony DX (Developer experience) efforts btw so might improve in the next releases.

     

    So, specify the env you use for web browsing in setup wizard and the site.

  3. In the "Setting up folder permission"-section, it would be nice if it was more clealy defined what is the user and what is a group in the example, instead of just overrall usage of www-data (especially the setcfacl commands). Thanks

  4. Seeing a 404 on ezsetup? Don't forget the htaccess/virtualhost configuration: Apache

  5. Hi, what about the cron configuration ?

    For eZ 4.x, we had to modify the system crontab to execute some cronjobs via runcronjobs.php.

    Using the hybrid mode (legacy/new stack), should we use the same crontab for eZPublish 5.x (and thus, run legacy scripts) ? Does eZ 5 still need it ?

     

     

     

  6. Valentin Nivuahc yes it is still needed on 5.x, basically the exact same needs as legacy given legacy is still bundled, however if you use hybrid stack they should be executed using the symfony console legacy script wrapper command.

    Feel free to open EZP issue against component Documentation so we can aim at adding some more information on that.