edit description

Manual Installation Guides

Introduction

Hi! You are about to install eZ Platform on your machine and this guide is here to make sure that the whole process of preparation and installation is fast and easy. This guide consists of a three paths that differ slightly; you should choose the one that meets your operating system:

Microsoft Windows, Mac OS X or other Unix-Based Systems.

Installation guides can be followed with any eZ Symfony distribution, you can find a list of available distributions from eZ in a table below:

Type	Archive	License	GIT / Composer
eZ Platform - "clean"	ezplatform.com	GPL	ezsystems/ezplatform (INSTALL.md)
eZ Platform - "demo"	Available via Git / Composer	GPL	ezsystems/ezplatform-demo
eZ Platform Enterprise Edition - "clean"	support.ez.no/Downloads	BUL (requires eZ Enterprise subscription)	ezsystems/ezplatform-ee (INSTALL.md)
eZ Platform Enterprise Edition - "demo"	support.ez.no/Downloads	BUL (requires eZ Enterprise subscription)	ezsystems/ezplatform-ee-demo

Installation Guide for OS X

Preparation:

1. Install MySQL

Download from the official MySQL webpage is strongly recommended.

2. Set up PHP

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.

a. Edit Apache2 configuration file:

sudo vi /private/etc/apache2/httpd.conf

b. Uncomment the following line:

LoadModule php5_module libexec/apache2/libphp5.so

c. If you can't locate the php.ini file on your machine, it's probably under php.ini.default. Create a new php.ini file based on defaults:

sudo cp /private/etc/php.ini.default /private/etc/php.ini

d. Open the file in a text editor (in this example, in vi):

sudo vi /private/etc/php.ini

e. Locate date.timezone and pdo_mysql.default_socket and provide them with values as in the example below:

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

f. Increase memory_limit value for eZ Platform:

memory_limit = 4G

3. Set up virtual host and start Apache2

a. Edit Apache2 configuration file:

sudo vi /private/etc/apache2/httpd.conf

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

c. Comment the following line:

Include /private/etc/apache2/extra/httpd-vhosts.conf

d. Add the following line to the file:

Include /private/etc/apache2/users/*.conf

e. Change permissions for virtual hosts storage directory (775):

sudo chmod -R 775 /private/etc/apache2/users
sudo chmod 775 /private/etc/apache2

4. Start Apache2 daemon using terminal

sudo apachectl start

5. Install Composer globally

Composer is a dependency manager that allows you to install packages directly in the project. It is also checking all packages' versions on a regular basis to make sure they are up-to-date and to avoid inconsistencies.

curl -sS https://getcomposer.org/installer | php
mkdir -p /usr/local/bin
php -d memory_limit=-1 composer.phar

6. Create a new database for eZ Platform

Create new database (you can substitute ez1 with the database name you want to use):

/usr/local/mysql/bin/mysql -u root -e 'create database ez1;'

7. Install Brew package manager

Brew is a package manager for OS X, if you haven't used it already you are going to love what it does!

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

8. Install additional requirements for eZ Platform

a. Install PEAR/PECL extension:

cd /usr/lib/php
curl -O https://pear.php.net/go-pear.phar
php -d detect_unicode=0 go-pear.phar
sudo php install-pear-nozlib.phar
sudo pear channel-update pear.php.net
sudo pecl channel-update pecl.php.net
sudo pear upgrade-all
sudo pear config-set auto_discover 1

b. Install autoconf:

brew install autoconf

c. Install intl:

brew install icu4c
sudo pecl install intl

d. The path to the ICU libraries and headers is: /usr/local/opt/icu4c/.

Edit /private/etc/php.ini and add following line:

extension=intl.so

e. Enable opcache extension for PHP (suggested, but not required) by adding:

zend_extension=opcache.so

Installation:

9. Install eZ Platform

a. Go to the folder with your installation and set up directory permissions:

chmod 775 ../ez1.lh
chmod 775 ../../workspace
chmod 775 ../../../Documents

b. Download archive from ezplatform.com. Extract the eZ Platform archive to a directory, then execute post install scripts.

cd /<directory>/
php -d memory_limit=-1 composer.phar run-script post-install-cmd

c. Copy the virtual host template:

sudo cp doc/apache2/vhost.template /private/etc/apache2/users/ez1.lh.conf

d. Edit the new virtual host:

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

e. Modify virtual host file vhost.template.

Replace the ---USER_ID--- variable (used in lines 10 and 17) with your current user ID. Use whoami command to get effective user ID of the currently logged user. If you want to use the default virtual host template (delivered with eZ Platform package) all you have to do is set up lines 7, 8, 9, 10, 17, 25 and 33:

f. Restart Apache 2 server:

sudo apachectl restart

g. Install required dependencies using Composer:

composer install

When Composer asks you for the token you must log in to your GitHub account and edit your profile. Go to the Personal access tokens link and Generate new token with default settings. Be aware that the token will be shown only once, so do not refresh the page until you paste the token into Composer prompt. This operation is performed only once when you install eZ Platform for the first time.

h. Change directory permissions:

rm -rf var/cache/* var/logs/* var/sessions/*
sudo chmod +a "_www allow delete,write,append,file_inherit,directory_inherit" var web/var
sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" var web/var

i. Install eZ Platform:

php bin/console ezplatform:install clean

You will be able to see your page under http://ez1.lh (or the address you chose in preparation). Please note that a clean install of eZ Platform doesn’t include DemoBundle anymore.

Enterprise

Enable Date-based Publisher

To enable delayed publishing of Content using the Date-based publisher, see below

10. Optional

a. Install PHP 5.6 with opcache extension:

brew install -v homebrew/php/php56
chmod -R ug+w $(brew --prefix php56)/lib/php
brew install -v php56-opcache

b. Add proper date.timezone settings:

sudo vi /usr/local/etc/php/5.6/php.ini

c. Uncomment and modify:

date.timezone = "Europe/Warsaw"
(…)
Increase memory_limit value for eZ Platform:
memory_limit = 4G
(…)

d. Disable errors showing:

display_errors = Off

e. Change default PHP parser used by Apache:

``` bash: sudo vi /private/etc/apache2/httpd.conf

f. Find and comment the following line:

``` bash
# LoadModule php5_module libexec/apache2/libphp5.so

g. Add below:

LoadModule php5_module /usr/local/opt/php56/libexec/apache2/libphp5.so

e. Install intl extension for PHP 5.6:

brew install php56-intl

f. Restart Apache:

sudo apachectl restart

Installation Guide for Unix-Based Systems

1. Install a LAMP Stack (*NIX, Apache, MySQL, PHP5+)

Depending on your selected *NIX distribution, you may need to install part or all of the LAMP stack required to run eZ Platform or eZ Enterprise. Before getting started, make sure you review our requirements page to see the systems we support and use for testing. You can try using an unsupported configuration, but your results may vary.

Please not that, while OS X is a *NIX-based system, it has its own unique requirements listed in our Installation Guide for OS X. Developer-maintained installation notes are kept in our GitHub repository at this location as well: https://github.com/ezsystems/ezplatform/blob/master/INSTALL.md

You may use your system's package manager (yum, apt-get, etc.) to obtain a copy of Apache, MySQL, and PHP, or download the latest versions from the official websites and install manually:

• Apache2
• MySQL
• PHP 5.6+

For Debian 8.5, for example, we'd recommend using apt-get to install apache2, mysql-server, mysql-client, and php5-* (all the packages listed in the requirements), as well as git for version control. If the system on which you're doing the install has only 1 or 2 GB of RAM, be sure to set up swap so you don't run out of RAM when running the composer scripts later on.

2. Get Composer

You'll need Composer, the PHP command line dependency manager.

a. Install Composer by running the following command on the terminal of the machine upon which you're installing eZ Platform:

php -r "readfile('https://getcomposer.org/installer');" | php

b. Move the downloaded composer.phar file to a globally-available path:

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

3. Download the desired version of eZ Platform or eZ Enterprise

• If you are installing eZ Platform, download the latest archive from ezplatform.com
• For licensed eZ Enterprise customers, download your file here: https://support.ez.no/Downloads

Expand the archive into /var/www/ezplatform or the folder name or your choosing.

For developers interested in working with the latest version of eZ Platform, you may also clone the latest from our GitHub repository:

cd /var/www
git clone https://github.com/ezsystems/ezplatform.git /var/www/ezplatform

You can rename the destination folder to whatever you like. This is where eZ Platform will live, and you'll point your virtual host to this folder to use as its root. You may choose to download an archive file from ezplatform.com instead of cloning from GitHub, and extract the eZ Platform archive to a similar directory. The subsequent steps are identical, regardless of the method you choose to obtain eZ Platform.

4. Create a new database for eZ Platform

Create new database (you can substitute ezplatform with the database name you want to use, but keep it in mind as you run the installation script):

/usr/bin/mysql -u root -e 'create database ezplatform;'

5. Run the Installation Scripts

Composer will look inside the composer.json file and install all of the required packages to run eZ Platform. There's a script in the bin folder called ./console that will install eZ Platform for your desired environment as well (dev or prod).

This is the step where you want to make sure you have swap configured for your machine if it does not have an abundance of RAM.

a. Run composer install:

cd /var/www/ezplatform
php -d memory_limit=-1 /usr/local/bin/composer install

Once the installer gets to the point that it creates app/config/parameters.yml, you will be presented with a few decisions. The first asks you to choose a secret; choose any random string you like, made up of characters, numbers, and symbols, up to around 32 characters. This is used by Symfony when generating CSRF tokens, encrypting cookies, and for creating signed URIs when using ESI (Edge Side Includes).

Next, you'll be asked to specify a database driver. You may press return to accept the default for this option, as well as the next several (database_host, database_port, database_name, database_user) unless you have customized those values and need to enter them as configured on your installation. If you set a password for your database user, enter it when prompted for database_password. The installer should continue once you've completed this manual portion of the installation process.

b. Run eZ Platform's installer:

php -d memory_limit=-1 /var/www/ezplatform/bin/console ezplatform:install --env prod clean

Don't forget to substitute any custom folder name you may have chosen in place of ezplatform/ after /var/www/ in the examples above. As you can see, this example shows a clean production installation. We're telling PHP to run Symfony's console to execute the ezplatform install script. You can get an informative output to learn more about the console script's capabilities by swapping in these parameters: config:dump-reference ezpublish

If Composer asks you for your token, you must log in to your GitHub account and edit your profile. Go to the Personal access tokens link and Generate new token with default settings. Be aware that the token will be shown only once, so do not refresh the page until you paste the token into the Composer prompt. This operation is performed only once when you install eZ Platform for the first time.

Please note that a clean install of eZ Platform doesn’t include the DemoBundle anymore.

Enterprise

Enable Date-based Publisher

To enable delayed publishing of Content using the Date-based publisher, you need to set up cron to run the command bin/console ezstudio:scheduled:publish periodically.

For example, to check for publishing every minute, add the following script:

echo '* * * * * cd [path-to-ezplatform]; php bin/console ezpublish:cron:run --quiet --env=prod' > ezp_cron.txt

For 5-minute intervals:

echo '*/5 * * * * cd [path-to-ezplatform]; php bin/console ezpublish:cron:run --quiet --env=prod' > ezp_cron.txt

Next, append the new cron to user's crontab without destroying existing crons. Assuming the web server user data is www-data:

crontab -u www-data -l|cat - ezp_cron.txt | crontab -u www-data -

Finally, remove the temporary file:

rm ezp_cron.txt

6. Setup the folder rights (*NIX users)

Like most things, Symfony documentation applies here, meaning var/cache and var/logs need to be writable by cli and web server user.

Furthermore, future files and directories created by these two users will need to inherit those access rights. For security reasons, there is no need for web server to have access to write to other directories.

Then, go to the Set up directory permissions page for the next steps of this settings.

7. Set up a Virtual Host

For our example, we'll demonstrate using Apache2 as part of the traditional LAMP stack.

Option A: Scripted Configuration

Instead of manually editing the vhost.template file, you may instead use the included shell script: /var/www/ezplatform/bin/vhost.sh to generate a configured .conf file. Check out the source of vhost.sh to see the options provided. Additional information is included in our Web Server documentation here as well.

Option B: Manual Edits

a. Copy the vhost template file from its home in the doc folder:

cp /var/www/ezplatform/doc/apache2/vhost.template /etc/apache2/sites-available/ezplatform.conf

b. Edit the file, substituting the %placeholders% with the appropriate values for your desired config:

vi /etc/apache2/sites-available/ezplatform.conf

For a DEV environment, you can change

• • <VirtualHost %IP_ADDRESS%:%PORT%>to <VirtualHost *:80>
  • ServerName %HOST_NAME%toServerName localhost
  • ServerAlias %HOST_ALIAS%...that can simply be deleted.
  • DocumentRoot %BASEDIR%/webtoDocumentRoot /var/www/ezplatform/web
  • LimitRequestBody %BODY_SIZE_LIMIT%toLimitRequestBody 0
  • TimeOut %TIMEOUT%toTimeOut 42to avoid waiting longer than 42 seconds for all the things.

Be sure to specify /var/www/ezplatform/web as the DocumentRoot and Directory. Uncomment the line that starts with #if[SYMFONY_ENV] and set the value, something like this:

# Environment.
# Possible values: "prod" and "dev" out-of-the-box, other values possible with proper configuration
# Defaults to "prod" if omitted (uses SetEnvIf so value can be used in rewrite rules)
SetEnvIf Request_URI ".*" SYMFONY_ENV=dev

8. Server Configuration (Apache as example)

Make sure you've got the libapache2-mod-php5 module installed for Apache2 to use PHP5.x, and have the rewrite module enabled:

apt-get -y install libapache2-mod-php5
a2enmod rewrite

a. You'll need the web user set as the owner/group on all your files to avoid a 500 error:

chown -R www-data:www-data /var/www/ezplatform

b. With your vhost file properly prepared and located in /etc/apache2/sites-available/ezplatform.conf, enable the VirtualHost and disable the default:

a2ensite ezplatform
a2dissite 000-default.conf

9. Restart server (Apache)

service apache2 restart

Set up Swap on Debian 8.x

Overview

Swap space allows your system to utilize the hard drive to supplement capacity when RAM runs short. Composer install will fail if there is insufficient RAM available, but adding swap will allow it to complete installation.

Solution

Via the command line, you can set up and enable swap on your Debian machine via the following commands (as root):

Set up Swap

fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo "/swapfile   none    swap    sw    0   0" >> /etc/fstab
sysctl vm.swappiness=10
echo "vm.swappiness=10" >> /etc/sysctl.conf
sysctl vm.vfs_cache_pressure=50
echo "vm.vfs_cache_pressure=50" >> /etc/sysctl.conf

Testing the Result

You should see the changes effected immediately, and can check via the command line:

Test the Result

# You should see swap in use now:
free -m

# Swappiness should now be 10
cat /proc/sys/vm/swappiness

# Cache pressure should be set to 50
cat /proc/sys/vm/vfs_cache_pressure

Manual Installation on Windows

Preparation:

1. Set up PHP

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. file name is httpd.conf and by default it is located in this directory:

C:\Program Files\Apache Software Foundation\Apache2.2\conf

a. Uncomment the following line:

LoadModule php5_module libexec/apache2/libphp5.so

b. Locate php.ini file. By default it should be in the following directory:

C:\program files\php\php.ini

c. Open the file in a text editor and locate date.timezone and pdo_mysql.default_socket and provide them with values as in the example below:

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

d. Increase memory_limit value for eZ Platform:

memory_limit = 4G

2. Set up virtual host and start Apache2

a. Edit Apache2 configuration file:

c:\Program Files\Apache Software Foundation\Apache2.2\conf

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

c. Comment the following line:

Include /private/etc/apache2/extra/httpd-vhosts.conf

d. Add the following line to the file:

Include /private/etc/apache2/users/*.conf

3. Start Apache2 daemon using Command Line

httpd.exe

4. Install Composer globally

Composer is a dependency manager that allows you to install packages directly in the project. It is also checking all packages' versions on a regular basis to make sure they are up-to-date and to avoid inconsistencies.

curl -sS https://getcomposer.org/installer | php
php -d memory_limit=-1 composer.phar

5. Create a new database for eZ Platform

Create new database (you can substitute ez1 with the database name you want to use):

mysql -uroot -ppassword -e "CREATE DATABASE ez1"

6. Install additional requirements for eZ Platform

a. Install PEAR/PECL extension:

cd c:\program files\php\php.ini
curl -O https://pear.php.net/go-pear.phar
php -d detect_unicode=0 go-pear.phar
php install-pear-nozlib.phar
pear channel-update pear.php.net
pecl channel-update pecl.php.net
pear upgrade-all
pear config-set auto_discover 1

b. Edit php.ini and add following line:

extension=intl.so

c. Enable opcache extension for PHP (suggested, but not required) by adding:

zend_extension=opcache.so

Installation:

7. Install eZ Platform

a. Download archive from ezplatform.com. Extract the eZ Platform archive to a directory, then execute post install scripts.

cd /<directory>/
php -d memory_limit=-1 composer.phar run-script post-install-cmd

b. Copy the virtual host template:

COPY c:\Program Files\Apache Software Foundation\Apache2.2\vhost.template c:\Program Files\Apache Software Foundation\Apache2.2\users/ez1.lh.conf

d. Modify virtual host file vhost.template.

Replace the ---USER_ID--- variable (used in lines 10 and 17) with your current user ID. Use whoami command to get effective user ID of the currently logged user. If you want to use the default virtual host template (delivered with eZ Platform package) all you have to do is set up lines 7, 8, 9, 10, 17, 25 and 33:

e. Restart Apache 2 server:

httpd.exe -k restart

f. Install required dependencies using Composer:

composer install

When Composer asks you for the token you must log in to your GitHub account and edit your profile. Go to the Personal access tokens link and Generate new token with default settings. Be aware that the token will be shown only once, so do not refresh the page until you paste the token into Composer prompt. This operation is performed only once when you install eZ Platform for the first time.

h. Install eZ Platform:

php bin/console ezplatform:install clean

You will be able to see your page under http://ez1.lh (or the address you chose in preparation). Please note that a clean install of eZ Platform doesn’t include DemoBundle anymore.

Enterprise

Enable Date-based Publisher

To enable delayed publishing of Content using the Date-based publisher, see above.