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:
1 | sudo vi /private/etc/apache2/httpd.conf |
b. Uncomment the following line:
1 | 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:
1 | sudo cp /private/etc/php.ini.default /private/etc/php.ini |
d. Open the file in a text editor (in this example, in vi):
1 | 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:
1 2 | date.timezone = "Europe/Warsaw" pdo_mysql.default_socket = /tmp/mysql.sock |
f. Increase memory_limit
value for eZ Platform:
1 | memory_limit = 4G |
3. Set up virtual host and start Apache2¶
a. Edit Apache2 configuration file:
1 | sudo vi /private/etc/apache2/httpd.conf |
b. Uncomment and modify the following lines:
1 2 | LoadModule vhost_alias_module libexec/apache2/mod_vhost_alias.so LoadModule rewrite_module libexec/apache2/mod_rewrite.so |
c. Comment the following line:
1 | Include /private/etc/apache2/extra/httpd-vhosts.conf |
d. Add the following line to the file:
1 | Include /private/etc/apache2/users/*.conf |
e. Change permissions for virtual hosts storage directory (775):
1 2 | sudo chmod -R 775 /private/etc/apache2/users sudo chmod 775 /private/etc/apache2 |
4. Start Apache2 daemon using terminal¶
1 | 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.
1 2 3 | 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):
1 | /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!
1 | ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" |
8. Install additional requirements for eZ Platform¶
a. Install PEAR/PECL extension:
1 2 3 4 5 6 7 8 | 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:
1 | brew install autoconf |
c. Install intl:
1 2 | 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:
1 | extension=intl.so |
e. Enable opcache extension for PHP (suggested, but not required) by adding:
1 | zend_extension=opcache.so |
Installation:¶
9. Install eZ Platform¶
a. Go to the folder with your installation and set up directory permissions:
1 2 3 | 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.
1 2 | cd /<directory>/ php -d memory_limit=-1 composer.phar run-script post-install-cmd |
c. Copy the virtual host template:
1 | sudo cp doc/apache2/vhost.template /private/etc/apache2/users/ez1.lh.conf |
d. Edit the new virtual host:
1 | 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:
1 | sudo apachectl restart |
g. Install required dependencies using Composer:
1 | 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:
1 2 3 | 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:
1 | 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:
1 2 3 | 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:
1 | sudo vi /usr/local/etc/php/5.6/php.ini |
c. Uncomment and modify:
1 2 3 4 5 | date.timezone = "Europe/Warsaw" (…) Increase memory_limit value for eZ Platform: memory_limit = 4G (…) |
d. Disable errors showing:
1 | display_errors = Off |
e. Change default PHP parser used by Apache:
``` bash: sudo vi /private/etc/apache2/httpd.conf
1 2 3 4 | f. Find and comment the following line: ``` bash # LoadModule php5_module libexec/apache2/libphp5.so |
g. Add below:
1 | LoadModule php5_module /usr/local/opt/php56/libexec/apache2/libphp5.so |
e. Install intl extension for PHP 5.6:
1 | brew install php56-intl |
f. Restart Apache:
1 | 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:
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:
1 | php -r "readfile('https://getcomposer.org/installer');" | php |
b. Move the downloaded composer.phar file to a globally-available path:
1 | 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:
1 2 | 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):
1 | /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:¶
1 2 | 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:¶
1 | 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:
1 | 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:
1 | 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:
1 2 3 4 | # 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:
1 2 | 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:
1 | 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:
1 2 | a2ensite ezplatform
a2dissite 000-default.conf
|
9. Restart server (Apache)¶
1 | 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
1 2 3 4 5 6 7 8 9 | 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
1 2 3 4 5 6 7 8 | # 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:
1 | C:\Program Files\Apache Software Foundation\Apache2.2\conf |
a. Uncomment the following line:
1 | LoadModule php5_module libexec/apache2/libphp5.so |
b. Locate php.ini file. By default it should be in the following directory:
1 | 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:
1 2 | date.timezone = "Europe/Warsaw" pdo_mysql.default_socket = /tmp/mysql.sock |
d. Increase memory_limit
value for eZ Platform:
1 | memory_limit = 4G |
2. Set up virtual host and start Apache2¶
a. Edit Apache2 configuration file:
1 | c:\Program Files\Apache Software Foundation\Apache2.2\conf |
b. Uncomment and modify the following lines:
1 2 | LoadModule vhost_alias_module libexec/apache2/mod_vhost_alias.so LoadModule rewrite_module libexec/apache2/mod_rewrite.so |
c. Comment the following line:
1 | Include /private/etc/apache2/extra/httpd-vhosts.conf |
d. Add the following line to the file:
1 | Include /private/etc/apache2/users/*.conf |
3. Start Apache2 daemon using Command Line¶
1 | 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.
1 2 | 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):
1 | mysql -uroot -ppassword -e "CREATE DATABASE ez1"
|
6. Install additional requirements for eZ Platform¶
a. Install PEAR/PECL extension:
1 2 3 4 5 6 7 8 | 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:
1 | extension=intl.so |
c. Enable opcache extension for PHP (suggested, but not required) by adding:
1 | 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.
1 2 | cd /<directory>/ php -d memory_limit=-1 composer.phar run-script post-install-cmd |
b. Copy the virtual host template:
1 | 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:
1 | httpd.exe -k restart |
f. Install required dependencies using Composer:
1 | 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:
1 | 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.