Installing eZ publish
出自Guoshuang Wiki
Unpacking the Installation
The first thing to do is download the latest distribution of eZ publish from http://ez.no/. The archives are normally available in tar.gz, tar.bz, and .zip file formats. Windows users should choose the .zip format for compatibility, and *NIX users can choose from the tar.gx or tar.bz formats. The most compatible method is to expand this archive on your own computer and then use FTP to transfer the files to the correct folder on your server.
Since the archive is only about 4MB in size compared to the 20MB size of the expanded archive, it makes sense to upload the archive and then extract it rather then uploading the extracted files individually. If you have command line access to the server, you can use the following UNIX commands to do this:
wget http://ez.no/downloads/ezpublish.3.x-x.tar.gz tar -xzf ezpublish-3.x-x.tar.gz
All files needed for installation will be extracted to a folder called ezpublish-3.x-x (where x is the version number). These files should then be transferred to the correct folder on your web server. Some web hosting packages have powerful control panels (such as CPanel or Ensim) that allow you to expand archives through their interface. If this is the case, you can upload the archive and use the control panel to expand it.
Once you have expanded the archive, you will find a number of files and folders. The most important of these are shown in the following table:
| Name | Function |
|---|---|
design
| This is where all of the default eZ publish templates are stored and is where you will create your new ones. |
index.php
| This is the main controller script for eZ publish. All requests to the website come via this. |
kernel
| This folder contains the main scripts that make eZ publish function. |
lib
| This folder contains all the additional libraries that add functionality to eZ publish. |
runcronjobs.php
| This script should be run regularly to ensure that various tasks are performed. |
settings
| This folder contains all of the default settings, as well as all the override settings that you will create. |
var
| This folder is used to store all the images and files that get uploaded and provides a location to store all the cache files that are generated. |
Initializing the Database
MySQL is the most commonly used database for eZ publish, so we have used it in these examples. All you need to do at this stage is create a database for eZ publish to use, and assign a user for that database. On many shared hosting solutions, a database already exists for you, and all you need to do is note down its name and the user name and password used to access it (which should have been provided with the hosting package). In case you need to set up the database yourself, perform the following steps:
1. With command line access, log in to the server on which the database is hosted and use the following command to launch the MySQL application:
mysql -u username -p
2. This will then prompt you for your password. Once you have logged in to the database, issue the following command to create the database:
CREATE DATABASE database_name;
This will create the database, but it will be accessible only to the user that you logged in as. For security reasons it is better to create a new user for this database, because if someone else were to somehow read your configuration files, your password would be compromised, because it is stored in plain text.
3. To create a user who only has access to this database, issue the following command:
GRANT ALL PRIVILEGES ON database_name.* TO username@localhost IDENTIFIED BY 'password';
If you do not have access to the command line, the best method is to install a web-based database administration tool such as phpMyAdmin, which will enable you to create the database and user using a web browser.
Apache Virtual Host Settings
Although it is possible to run eZ publish in a subfolder of a website, it works extremely well when set up properly as a virtualhost in Apache with mod_rewrite enabled (this also increases security, because all requests are directed to index.php). eZ publish uses URLs such as /node/view/253 to view a node in the CMS. Mod_rewrite means that this URL could be translated into something like /contact/, which is far more meaningful and memorable to the end user. Most hosting services have mod_rewrite enabled as it is on by default in Apache. If you can't access your httpd.conf file for apache, it is still possible to enable rewriting by using a .htaccess file in the root of your eZ publish directory.
If you have access to the settings for your virtual host, you need to set it up as follows:
<VirtualHost *> DocumentRoot /path/to/ezpublish ServerName test.ez.local <Directory /path/to/ezpublish> Options FollowSymLinks Indexes ExecCGI AllowOverride None </Directory> RewriteEngine On RewriteRule !\.(js|gif|css|jpg|png)$ /path/to/ezpublish/index.php </VirtualHost>
The most important lines in this code are the rewrite statements at the end. If you already have a working virtualhost configuration, just add these two lines to it, rather than copying this whole setup. If you are able to override the settings for mod_rewrite in your htaccess files (check with your hosting provider), you can place a file called .htaccess containing the following lines in the root of your installation. This is the default name, and what 99% of hosting providers use, but it pays to check first!
RewriteEngine On RewriteRule !\.(js|gif|css|jpg|png)$ /path/to/ezpublish/index.php
Image Settings
eZ publish uses server-side image manipulation utilities to create the different versions of images that you will upload. For example, if you upload a large photograph, eZ publish can resize it to a size you specify and then create thumbnails at a size you specify. There are two main utilities that do this: ImageMagick and GD. ImageMagick is the more powerful of the two, being able to apply a number of effects (such as border, blur, twirl, etc.) to the image, but both perform equally well for the simple requirement of resizing.
ImageMagick
ImageMagick is the more powerful of the two utilities, and is used to add many different effects to the images you upload. It is a standalone binary located on the server and often needs to be installed manually. If your server is running on a UNIX-based system and you have full access to the machine, installation is simple. Download the binary for your system (or the source if you have an unusual setup) from http://www.imagemagick.org and follow the guide for installing it. If you are running Windows, it is also possible to download a binary for your system from this source. If you have limited access to your system, first check if your hosting provider is willing to install it. Otherwise, depending on your system limitations it may be possible to upload the binary. If you do perform a custom installation, remember that eZ publish must be able to locate the convert binary before it can use it. If stored in a normal location, it will be found automatically, but if it is in a custom location, specify this in /settings/override/image.ini.append.php:
[ImageMagick] IsEnabled=true ExecutablePath=/path/to/binary Executable=convert
GD
GD is a library for image manipulation that has to be compiled into PHP to run. In recent versions of PHP (>4.3), GD is included by default, which makes life a lot easier. GD is less powerful than ImageMagick, and is normally used only as a fallback if ImageMagick is not found. Hosting providers running the latest versions of PHP will obviously have GD, but those running older versions of PHP are unlikely to add it to their existing installation as it requires rebuilding PHP. Visit http://www.boutell.com/gd for more information on the GD library.
If you are using a GD version prior to v2, image scaling will look bad because those versions used a very simple re-sampling algorithm.
Cron Jobs
It is necessary to have a regularly executed script to execute various tasks that need to be carried out periodically. These tasks include the execution and processing of workflows and the issuing of notifications to users via e-mail. On the most common setup, a UNIX‑based system, the best way of doing this is to set up a cron job that runs approximately every 15 minutes. A cron job is simply an automated process that uses a script to carry out various tasks periodically. Most systems have crontabs for individual users; these are programs that allow users to define cron jobs. You will need to edit the crontab file for your system and add the following lines:
#This must be set to the directory where eZ publish is installed. EZPUBLISHROOT=/path/to/your/ezpublish/directory # Location of the PHP Command Line Interface binary. PHP=/usr/local/bin/php # Executes the runcronjobs.php script every 15th minute. 0,15,30,45 * * * * cd $EZPUBLISHROOT; $PHP -C runcronjobs.php -q 2>&1
This will execute the runcronjobs.php script from the command line every 15 minutes. If you are not able to set up this task, the site will still be useable, but some features, such as the ones mentioned, will not function properly. On a Windows system you need to use the Scheduled Tasks mechanism to execute a batch file, which would execute the runcronjobs.php script.
Configuration Files
eZ Publish is configured through a collection of files known as ini files, located in the settings directory. The Setup wizard, which we discuss in the next part of this chapter, automatically defines some settings for these files, but it is necessary to understand how these are used in order to modify an eZ publish installation.
In the root of the settings folder are the default configuration files that come with the installation. Two folders, override and siteaccess, are used to modify these default settings to make the site work for you. The siteaccess folder is used to configure multiple views of the site and contains subfolders that correspond to the name set up for the site. For example, there may be subfolders called admin and plain. The order in which these locations are read is:
1. The default configuration files in the settings folder
2. The files in the siteaccess folder corresponding to the current view
3. The files in the override folder
The order of precedence of files according to their location is override > siteaccess > settings.
Although there are many configuration files (about 30 at the last count, and more are added every time a new feature is added) you generally need to tweak only a few:
| Configuration File | Comments |
|---|---|
site.ini
| The main configuration file for the site; covers database settings, site access list, and cache settings |
override.ini
| Defines the template overrides for the different sites defined |
image.ini
| Defines the different image presets for the sites |
i18n.ini
| Defines the different language setups for the sites |
In general, there will be a site.ini file in the override folder, which defines the database access for the entire site because the database access will be the same for both the user site and the admin site. More site-specific settings, such as the template overrides in override.ini, will be in the siteaccess folder because they vary between the different site accesses. The files image.ini and i18n.ini will often be specific to individual sites because these settings depend upon the audience and the design.
The eZ publish configuration files can have a number of different file endings: .ini, .ini.append, and .ini.append.php. eZ publish will search for files with all of these endings in the relevant folders.
The recommended extension is .ini.append.php, because if the file were somehow requested through the web server, it would be served as a standard PHP file, and since the configuration lines are interpreted as standard PHP comments, there would be no output.
Several ini files will be discussed throughout the book as we encounter more features of eZ publish that need to be configured and controlled.
The Setup Wizard
eZ publish has a very user-friendly setup system that takes you through all of the parameters necessary for setup and checks the system to make sure that everything is configured correctly. We will now go through all of the steps in turn to explain what they mean and what needs doing at each stage. Point your browser to the location in which you extracted the eZ publish setup files to start the Setup Wizard.
Page 1 of the Setup Wizard: Welcome to eZ publish
This is the first page of the setup wizard. By clicking Next you will be taken through a series of steps to configure eZ publish for your system. It will automatically detect the image system you are able to use. If you have ImageMagick installed it will use that, otherwise it will attempt to use GD if it is compiled into PHP. You can tell if it has found a usable system by looking at the bottom right part of the next screen, under Image System.
Page 2 of the Setup Wizard: System Check
The setup wizard checks the permissions for various directories that eZ publish uses to run. These are:
/var
| Used by eZ publish to store all the image files and the cache files |
/settings
| Used by eZ publish to store the settings |
/design
| Used by eZ publish to store the design templates |
If the permissions are not correct, you can use the script shown on the page to set their permissions, or use your FTP client to change the permissions for each folder to 777, which means they are writeable by the web server. There is an issue with this command if you are on a shared hosting environment, other users may be able to access these files. If this is a problem, you should look for dedicated hosting. Note that if you are able to change the owner of files on the web server, you can make these files belong to the web server user and disallow access to others. The command to do this is:
chmod R og+rwx var chown R user.group var
where user.group is the username and the group that the web server process runs under.
If everything is already set up properly, you will not see this page. When you click Next, the check will be run again unless you have selected Ignore this test.
Page 3 of the Setup Wizard: Email Settings
For eZ publish to send out e-mails to users, it must be configured to use a mail server. If you are using a UNIX-based system, you can normally use the local sendmail program. If you are using Windows or for some reasons do not have sendmail installed, you can use an external SMTP server to send your mails.
Page 4 of the Setup Wizard: Choose a Database
This is a particularly simple stage and lets you choose between MySQL and PostgreSQL as your database of choice. PostgreSQL includes some more advanced features that are not present in MySQL, although these do not greatly affect the running of eZ publish.
If you don't have a reason for wanting to run PostgreSQL, you probably don't need to!
Page 5 of the Setup Wizard: Database Initialization
When we set up the database user earlier in this chapter, we defined a username and password. This is where you enter them. You do not need to select a database at this point because eZ publish will only let you choose from the databases you have access to.
If eZ publish cannot connect to the database using the credentials you have supplied, you will have to repeat this step until it can. Recheck the user name, password, and privileges you set up earlier if this happens.
Page 6 of the Setup Wizard: Language Support
eZ publish has very strong support for multi-language installations. At this stage you can choose a default language as well as any other languages you need setting up on the system. Languages can be added at a later stage if necessary, so do not add languages here if you aren't sure you need to.
Page 7 of the Setup Wizard: Site Packages
The best way of getting to know eZ publish is by installing one of the pre-configured site packages and playing around with it. By default, eight site packages come bundled with eZ publish to fulfill a number of different needs. Choose the Plain site package if you are planning on building your own site from scratch. Otherwise, it may be simpler to modify an existing package. Each site is unique and requires its own database.
| Site | Description |
|---|---|
| Blog | A simple blog setup with dated posts |
| Corporate | A multi-section site with a simple corporate look and feel |
| Forum | A user forum, similar to the forums at http://ez.no |
| Gallery | A powerful gallery using eZ publish s image-handling system |
| Intranet | A typical corporate intranet |
| News | A news site with news stories in different categories |
| Plain | The no-frills setup to use if you need to roll your own site |
| Webshop | A sample e-commerce application using eZ publish s shop functionality |
Page 8 of the Setup Wizard: Site Access Configuration
The different sections of the site can be accessed in a number of different ways.
| Access Type | Description | Example URL |
|---|---|---|
| URL | The simplest method of accessing different sections of the site. | http://www.mysite.com/admin |
| Port | It is possible to assign a port through which to access your site. This is more complex to set up and requires custom Apache configuration. | http://www.mysite.com:81/ |
| Hostname | Specific host names can be used to decide which part of the site is accessed. This is more complex to set up and requires custom Apache configuration as well as adding DNS entries for the different hosts. | http://admin.mysite.com |
Page 9 of the Setup Wizard: Site Details
At this stage you can choose the title for the site and set up the URL that will be used to access it. It's also possible to fill in the administrator's e-mail and set up the paths that will be used to access the admin and user sections of the site. If the database already contains some data, this page will reappear and ask you what to do. Possible actions are:
- Leave the data and add new
- Remove existing data
- Leave the data and do nothing
- I've chosen a new database
Page 10 of the Setup Wizard: Site Security
If you cannot use the virtualhost mode, you will need to use an htaccess file to secure your system. There is an example .htaccess file in the root of the distribution that if renamed from .htaccess_root to .htaccess will make the setup secure. If you are running in virtualhost mode you will not see this screen.
Page 11 of the Setup Wizard: Site Registration
This page of the setup allows you to send an e-mail to eZ systems to let them know the details of the set up of the system you are using. Although this is optional, it is good practice because they will be able to focus their developments upon the areas that are useful for the most users.
Page 12 of the Setup Wizard: Finished
At this stage the site setup is finished. Make a note of the URLs on this page as they will be used to access your site in future.
Troubleshooting
Once you have reached this point you should have a fully functional eZ publish site to start working with. If you've hit a snag, there are a few common issues you can look at to get things working.
PHP Memory Limits
A common problem in hosting environments is that the memory limit of PHP is set too low. The default value of the limit is 8MB, but this is too low for eZ publish to run (although the eZ team has been working hard at reducing memory consumption). If you get output similar to the following, then you have this problem:
Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 184320 bytes) in /www/ezsite/kernel/classes/ezpackage.php on line 2140 Fatal error: eZ publish did not finish its request The execution of eZ publish was abruptly ended, the debug output is present below.
There is an easy fix to this if you are allowed to override the PHP settings using a .htaccess file (if your host doesn't support this, you may need to look for a new host) placed in the root of the eZ publish installation. In this file, add the following line:
php_value memory_limit "16M"
This will raise the memory limit to 16MB. If this still does not work, continue raising the limit until it does. In general, you will not have to go over 32MB for the site to work.
You may need to increase this setting later, if your pages are very complex.
PHP Running as a CGI
If your hosting provider is running PHP as a CGI instead of an Apache module, then eZ publish will have problems. The main symptom of this is that regardless of the link you click on, you will always get the front page of the site. The only way of fixing this problem (in versions of eZ publish prior to 3.4) is to modify ezsys.php, one of the eZ publish files. There are a number of posts in the forums at http://ez.no describing how to do this.
Fortunately, one of the outlined features for version 3.4 of eZ publish is a fix for this problem, so the best thing is to use this version when it becomes available.
To tell if your host is running PHP as a CGI, create a PHP file on your server containing the following script:
<?php if (php_sapi_name() == 'cgi') echo "PHP is running as a cgi"; else echo "PHP is running as a module"; ?>
Source
The source of this content is Chapter 1: Installing eZ publish of Learning eZ publish 3 : Building content management solutions by Paul Forsyth, Ben Pirt, Paul Borgermans, Bjorn Dieding, Martin Bauer, Tony Wood (Packt Publishing , 2004).
