Path

ez.no / documentation / ez publish / technical manual / 4.x / installation / manual installation / manual configuration of ez...


Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Manual configuration of eZ Publish

This part of the 4.x documentation is for eZ Publish 4.0, only reference section is common for all eZ Publish 4.x versions as well as eZ Publish 5.x "LegacyStack", please select the version you are using for the most up to date documentation!

This section describes how to manually configure eZ Publish instead of using the setup wizard to do all the work. Keep in mind that the manual installation method is for expert users only. It should only be used by people who know what they are doing. The following steps will work on both Linux/UNIX and Windows environments.

Database initialization

A clean eZ Publish database is created using two very important SQL scripts: "kernel_schema" and "cleandata" (note that an empty database should be created before launching these scripts). The first of them initializes the necessary database structure and the second one imports the pre-defined data to the database. While the "kernel_schema" script differs for each database engine, the "cleandata" script is the same for all solutions.

MySQL

Use the following command to run the MySQL specific "kernel_schema" script:

$ mysql -u USERNAME -pPASSWORD DATABASE < PATH/kernel/sql/mysql/kernel_schema.sql

In eZ Publish 4.0.1 and later versions, the script will use the InnoDB storage engine when creating new tables. This storage engine is recommended (and will be required in the future) for running eZ Publish on a MySQL database. Contact your database administrator if you are unsure about whether InnoDB is available on your server.

In eZ Publish 4.0.0, the CREATE TABLE statements in the "kernel_schema" script do not specify which storage engine to use (no ENGINE or TYPE option), and thus the default storage engine will be used. Normally, it is MyISAM. Because of this, it is highly recommended to set the default storage engine to InnoDB before you run the "kernel_schema" script (refer to the MySQL documentation for information about how to set the default engine). Alternatively, you can run the "kernel_schema" script first and then convert the newly created tables to InnoDB. You can either use the "bin/php/ezconvertmysqltabletype.php" script for database conversion (recommended) or convert the tables individually by using the following SQL query for each table:

ALTER TABLE <name_of_table> TYPE = innodb;

Use the following command to run the generic "cleandata" script:

$ mysql -u USERNAME -pPASSWORD DATABASE < PATH/kernel/sql/common/cleandata.sql

USERNAME

The MySQL user (if no user is set up, use "root").

PASSWORD

The password that belongs to the username.

DATABASE

The name of the database, for example "my_database".

PATH

The full path to the root directory of your eZ Publish installation, for example "/opt/ezp".

File permissions

Windows users can skip this part. If eZ Publish is installed on a Linux/UNIX based system, some of the file permissions need to be changed. There is a shell script that takes care of this. This script must be run, otherwise eZ Publish will not function properly. The script needs to be run from within the eZ Publish directory:

$ cd /opt/ezp
$ bin/modfix.sh

Replace "/opt/ezp" with the full path to the root directory of your eZ Publish installation.

The modfix script recursively alters the permission settings of the following directories inside the eZ Publish installation:

  • var/*
  • settings/*
  • design/*
  • autoload/*

Note that due to a bug in eZ Publish 4.0.0, the modfix script did not alter the permission settings for the "autoload" directory. This problem was fixed in eZ Publish 4.0.1.

If you know the user and group of the webserver it is recommended to use a different set of permissions:

# chown -R user.usergroup var/ settings/ design/ autoload/
# chmod -R 770 var/ settings/ design/ autoload/

The "user.usergroup" notation must be changed to user and group name that the webserver runs as.

Configuring eZ Publish

The "site.ini.append.php" configuration file located in the "settings/override" directory of your eZ Publish installation must be changed, or else eZ Publish will not function properly. This file is the global override for the site.ini configuration file. There are a lot of things that need to be configured (database, mail transport system, var directory, etc.). The following text shows a generic example of a configuration that can be used:

<?php /* #?ini charset="utf-8"?
 
[DatabaseSettings]
DatabaseImplementation=ezmysql
Server=localhost
User=root
Password=
Database=my_database
 
[FileSettings]
VarDir=var/example
 
[Session]
SessionNameHandler=custom
 
[SiteSettings]
DefaultAccess=example
SiteList[]
SiteList[]=example
 
[SiteAccessSettings]
CheckValidity=false
AvailableSiteAccessList[]
AvailableSiteAccessList[]=example
AvailableSiteAccessList[]=example_admin
RelatedSiteAccessList[]
RelatedSiteAccessList[]=example
RelatedSiteAccessList[]=example_admin
MatchOrder=host;uri
 
# Host matching
HostMatchMapItems[]=www.example.com;example
HostMatchMapItems[]=admin.example.com;example_admin
 
[InformationCollectionSettings]
EmailReceiver=webmaster@example.com
 
[MailSettings]
Transport=sendmail
AdminEmail=webmaster@example.com
EmailSender=test@example.com
 
[RegionalSettings]
Locale=eng-GB
ContentObjectLocale=eng-GB
TextTranslation=disabled
 
*/ ?>

In the example above the "AvailableSiteAccessList[]" array located in the "[SiteAccessSettings]" section of this file determines the available siteaccesses called "example" and "example_admin". The "CheckValidity" setting located in the same section should be set to false, otherwise the setup wizard will be initiated when trying to access the site.

In addition, two siteaccess configurations must be created, a public siteaccess ("example") and an administration siteaccess ("example_admin"). The following sub-directories have to be created in the root of your eZ Publish installation:

  • settings/siteaccess/example
  • settings/siteaccess/example_admin

Both siteaccesses must have a file called "site.ini.append.php".

The public siteaccess

The following text shows a generic solution for the "example" siteaccess:

<?php /* #?ini charset="utf-8"?
 
[SiteSettings]
SiteName=Example
SiteURL=www.example.com
LoginPage=embedded
 
[SiteAccessSettings]
RequireUserLogin=false
ShowHiddenNodes=false
 
[DesignSettings]
SiteDesign=example
 
[ContentSettings]
ViewCaching=disabled
 
[TemplateSettings]
TemplateCache=disabled
TemplateCompile=disabled
#ShowXHTMLCode=enabled
#Debug=enabled
 
[DebugSettings]
DebugOutput=enabled
Debug=inline
#DebugRedirection=enabled
 
[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=eng-GB
ShowUntranslatedObjects=disabled
 
*/ ?>

The admin siteaccess

The following text shows a generic solution for the "example_admin" siteaccess:

<?php /* #?ini charset="utf-8"?
 
[SiteSettings]
SiteName=Example
SiteURL=admin.example.com
LoginPage=custom
 
[SiteAccessSettings]
RequireUserLogin=true
ShowHiddenNodes=true
 
[DesignSettings]
SiteDesign=admin
 
[ContentSettings]
CachedViewPreferences[full]=admin_navigation_content=0;admin_navigation_details=0;admin_navigation_languages=0;admin_navigation_locations=
0;admin_navigation_relations=0;admin_navigation_roles=0;admin_navigation_policies=0;admin_navigation_content=0;admin_navigation_translatio
ns=0;admin_children_viewmode=list;admin_list_limit=1;admin_edit_show_locations=0;admin_url_list_limit=10;admin_url_view_limit=10;admin_sec
tion_list_limit=1;admin_orderlist_sortfield=user_name;admin_orderlist_sortorder=desc;admin_search_stats_limit=1;admin_treemenu=1;admin_boo
kmarkmenu=1;admin_left_menu_width=13
 
[DebugSettings]
DebugOutput=disabled
Debug=inline
 
[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=eng-GB
ShowUntranslatedObjects=enabled
 
*/ ?>

Note that database settings, mail settings, regional and other settings defined in "settings/override/site.ini.append.php" will be used for each siteaccess regardless of what is specified in the siteaccess settings. In the example above, the "Database=my_database" is specified under the "[DatabaseSettings]" section of this file so this database will be used for both "example" and "example_admin" siteaccesses. Refer to the "Site management" and "Configuration" sections of the "Concepts and basics" chapter for more information.

Unicode support

There is no need to override the "i18n.ini" configuration file since Unicode support is enabled by default in eZ Publish 4.

Languages

Available languages and their priorities can be controlled per siteaccess using the "SiteLanguageList" configuration setting located under the "[RegionalSettings]" section of the siteaccess "site.ini.append.php" file. If this setting is not specified, the system will use the old "ContentObjectLocale" setting and thus only the default language will be shown. Refer to the "Configuring the site languages" section for more information and examples.

The "cleandata.sql" script creates only one language which is the British English (eng-GB). All other languages should be added using the "Setup - Languages" part of the administration interface (http://admin.example.com in the example above).

Dynamic tree menu

If you have a large site with many nodes, it is strongly recommended to enable the "Dynamic" switch for your administration siteaccess. This will make the left tree menu in the administration interface work much faster and decrease the usage of network bandwidth.

Administrator's login and password

The following username and password are set by the "creandata.sql" script and can be used for logging in to the administration interface.

  • Username: admin
  • Password: publish

It is strongly recommended to change this password as soon as possible. Note that if you need another username for site administrator, you can create a new administrator user, log in as this user and remove the old one.

Balazs Halasy (03/05/2005 8:28 am)

Ricardo Correia (17/04/2013 9:51 am)

Julia Shymova, Svitlana Shatokhina, Geir Arne Waaler, Ricardo Correia


Comments

  • Some other INI files

    When you use the setup wizard and use the plain site package, some other INI files than site.ini are initialized as well.

    This documentation page should list them all, especially for the admin site access (toolbar.ini, icon.ini, ...).
  • Wrong file permissions

    Making files executable and writable by the web server as suggested above is a potential security risk.

    Instead of
    # chmod -R 770 var/ settings/ design/ autoload/
    

    I suggest to use set rights for files and directories separately, and give less permissions to group:

    # find var/ settings/ design/ autoload/ -type d | xargs chmod 750
    # find var/ settings/ design/ autoload/ -type f | xargs chmod 640
    

    • Re: Wrong file permissions

      So, the definitive secure solution as to file permission is meinhard benn's solution?

      But, anyhow, by giving ownership to the webserver user and his group means anytime a developer needs to access a file he'll need to work as root? ...mmhhh