Manual configuration of eZ Publish

This section describes how to manually configure eZ Publish inst= ead of using the setup wizard to do all the work. Keep in mind that the man= ual 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 i= nitialization

A clean eZ Publish database is created using two very important SQL scri= pts: "kernel_schema" and "cleandata" (note that a= n empty database should be created before launching these scripts). The fir= st of them initializes the necessary database structure and the second one = imports the pre-defined data to the database. While the "kernel_schem= a" 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:

=20
$ mysql -u USERNAME -pPASSWORD DATABASE < PATH/ezpublish_legacy/ker=
nel/sql/mysql/kernel_schema.sql=20


 
In eZ Publish 4.0.1 and later versions, the script will use the InnoDB s=
torage engine when creating new tables. This storage engine is recommended =
(and will be required in the future) for running eZ Publish on a MySQL data=
base. Contact your database administrator if you are unsure about whether I=
nnoDB 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 (ref= er to the MySQL documentation for= information about how to set the default engine). Alternatively, you can r= un the "kernel_schema" script first and then convert the newly= created tables to InnoDB. You can either use the "bin/p= hp/ezconvertmysqltabletype.php" script for database conversion (reco= mmended) or convert the tables individually by using the following SQL quer= y for each table:

=20

ALTER TABLE <name_of_table> TYPE =3D innodb;

=20

Use the following command to run the generic "cleandata" sc= ript:

=20

$ mysql -u USERNAME -pPASSWORD DATABASE < PATH/ezpublish_legacy/ker=
nel/sql/common/cleandata.sql

=20

USERNAME	The MySQL user (if no user is set up, use "ro= ot").
PASSWORD	The password that belongs to the username.
DATABASE	The name of the database, for example "my_dat= abase".
PATH	The full path to the root directory of your e= Z Publish installation, for example "/opt/ezp".

File permissions<= /h2>

Windows users can skip this part.

Several cache, log and config folders must be writable both by the web s= erver and the command line user, use one of the following alternat= ives to do this:

Using ACL on a system that supports chmod +a
The= se shell commands will give proper permission to the web server and command= line users:

=20

    $ cd /<ezp5-root>/
    $ rm -rf ezpublish/cache/*
    $ rm -rf ezpublish/logs/*
    $ sudo chmod +a "www-data allow delete,write,append,file_inherit,direct=
ory_inherit" \
      ezpublish/{cache,logs,config} ezpublish_legacy/{design,extension,sett=
ings,var} web
    $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,direct=
ory_inherit" \
      ezpublish/{cache,logs,config} ezpublish_legacy/{design,extension,sett=
ings,var} web

=20

Using ACL on a system that does not support chmod +a
Some systems don't support chmod +a, but do support another utility ca= lled setfacl. You may need to enable ACL support on your partition and inst= all setfacl before using it (as is the case with Ubuntu), like so:

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

Using chown on systems that don't support ACL
So= me systems don't support ACL at all. You will either need to set your web s= erver's user as the owner of the required directories.

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

Using chmod
If you can't use ACL and aren't allo= wed to change owner, you can use chmod, making the files writable by everyb= ody. Note that this method really isn't recommended as it allows any user t= o do anything.

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

Link assets

To be able to run eZ Publish 5 correctly, assets need to be exposed in t= he public "web" folder.

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

=20
cd /<ezp5-root> php ezpublish/console assets:install --symlink web php ezpublish/console ezpublish:legacy:assets_install --symlink web # For 5.1 / 2013.4 and higher, also: php ezpublish/console assetic:dump --env=3Dprod web
=20

Note: In both cases "web" is = the default folder and can be skipped from the command. Further information= about alternative options is available with -h just= like it is with "php ezpublish/console -h".

Warning regarding APC

If you are planning to use APC to speed up your site, please be sure to = check the available notes here, before entering the setup wizard chapter.

Configuring = eZ Publish

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

=20
<?php /* #?ini charset=3D"utf-8"? =20 [DatabaseSettings] DatabaseImplementation=3Dezmysql Server=3Dlocalhost User=3Droot Password=3D Database=3Dmy_database =20 [FileSettings] VarDir=3Dvar/example =20 [Session] SessionNameHandler=3Dcustom =20 [SiteSettings] DefaultAccess=3Dexample SiteList[] SiteList[]=3Dexample =20 [SiteAccessSettings] CheckValidity=3Dfalse AvailableSiteAccessList[] AvailableSiteAccessList[]=3Dexample AvailableSiteAccessList[]=3Dexample_admin RelatedSiteAccessList[] RelatedSiteAccessList[]=3Dexample RelatedSiteAccessList[]=3Dexample_admin MatchOrder=3Dhost;uri =20 # Host matching HostMatchMapItems[]=3Dwww.example.com;example HostMatchMapItems[]=3Dadmin.example.com;example_admin =20 [InformationCollectionSettings] EmailReceiver=3Dwebmaster@example.com =20 [MailSettings] Transport=3Dsendmail AdminEmail=3Dwebmaster@example.com EmailSender=3Dtest@example.com =20 [RegionalSettings] Locale=3Deng-GB ContentObjectLocale=3Deng-GB TextTranslation=3Ddisabled =20 */ ?>
=20

In the example above the "AvailableSiteAccessList[]" array = located in the "[SiteAccessSettings]" section of this file det= ermines the available siteaccesses called "example" and = "example_admin". The "CheckValidity" setting loca= ted 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 sit= eaccess ("example") and an administration siteaccess ("e= xample_admin"). The following sub-directories have to be created in = the root of your eZ Publish installation:

ezpublish_legacy/settings/siteaccess/example

ezpublish_legacy/settings/siteaccess/example_admin

Both siteaccesses must have a file called "site.ini.append.php".
The public si= teaccess The following text shows a generic solution for the "example" siteaccess: =20 <?php /* #?ini charset=3D"utf-8"? =20 [SiteSettings] SiteName=3DExample SiteURL=3Dwww.example.com LoginPage=3Dembedded =20 [SiteAccessSettings] RequireUserLogin=3Dfalse ShowHiddenNodes=3Dfalse =20 [DesignSettings] SiteDesign=3Dexample =20 [ContentSettings] ViewCaching=3Ddisabled =20 [TemplateSettings] TemplateCache=3Ddisabled TemplateCompile=3Ddisabled #ShowXHTMLCode=3Denabled #Debug=3Denabled =20 [DebugSettings] DebugOutput=3Denabled Debug=3Dinline #DebugRedirection=3Denabled =20 [RegionalSettings] SiteLanguageList[] SiteLanguageList[]=3Deng-GB ShowUntranslatedObjects=3Ddisabled =20 */ ?>=20 The admin site= access The following text shows a generic solution for the "example_admin= " siteaccess: =20 <?php /* #?ini charset=3D"utf-8"? =20 [SiteSettings] SiteName=3DExample SiteURL=3Dadmin.example.com LoginPage=3Dcustom =20 [SiteAccessSettings] RequireUserLogin=3Dtrue ShowHiddenNodes=3Dtrue =20 [DesignSettings] SiteDesign=3Dadmin =20 [ContentSettings] CachedViewPreferences[full]=3Dadmin_navigation_content=3D0;admin_navigation= _details=3D0;admin_navigation_languages=3D0;admin_navigation_locations=3D0;= admin_navigation_relations=3D0;admin_navigation_roles=3D0;admin_navigation_= policies=3D0admin_navigation_content=3D0;admin_navigation_translations=3D0;= admin_children_viewmode=3Dlist;admin_list_limit=3D1;admin_edit_show_locatio= ns=3D0;admin_url_list_limit=3D10;admin_url_view_limit=3D10;admin_section_li= st_limit=3D1;admin_orderlist_sortfield=3Duser_name;admin_orderlist_sortorde= r=3Ddesc;admin_search_stats_limit=3D1;admin_treemenu=3D1;admin_bookmarkmenu= =3D1;admin_left_menu_width=3D13 =20 [DebugSettings] DebugOutput=3Ddisabled Debug=3Dinline =20 [RegionalSettings] SiteLanguageList[] SiteLanguageList[]=3Deng-GB ShowUntranslatedObjects=3Denabled =20 */ ?>=20 Note that database settings, mail settings, regional and other settings = defined in "ezpublish_legacy/settings/override/site.ini.append.php" will be used for each siteaccess regardless of what is specified in t= he siteaccess settings. In the example above, the "Database=3Dmy_data= base" is specified under the "[DatabaseSettings]" secti= on of this file so this database will be used for both "example" and "example_admin" siteaccesses. Refer to the "Site mana= gement" and "Configuration" sections of the "Concepts and basics" chapter for mor= e information. Activate b= ase extensions There are some legacy extensions that need to be active, as eZ Publish d= epends on them. This is usually done in the ezpublish_legacy/settings/override/site.ini.append.php settings file. H= ere's an example of the extensions that you should activate: =20 [ExtensionSettings] ActiveExtensions[]=3Dezjscore ActiveExtensions[]=3Dezoe ActiveExtensions[]=3Dezformtoken ActiveExtensions[]=3Dezwt ActiveExtensions[]=3Dezie=20 Languages Available languages and their priorities can be controlled per siteacces= s using the "SiteLanguageList" configuration s= etting located under the "[RegionalSettings]" section of the s= iteaccess "site.ini.append.php" file. If this setting is not s= pecified, the system will use the old "Co= ntentObjectLocale" setting and thus only the default language wi= ll be shown. Refer to the "Configuring the site languages" sec= tion 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 administra= tion siteaccess. This will make the left tree menu in the administration in= terface work much faster and decrease the usage of network bandwidth. = Administrator's log-in and password The following user name and password are set by the "cleandata.sql= " script and can be used for logging in to the administration interf= ace. User name:=20 admin Password:=20 publish It is strongly recommended to change this password as soon as possible. = Note that if you need another user name for site administrator, you can cre= ate a new administrator user, log in as this user and remove the old one. Genera= te eZ Publish autoloads The autoloads can be generated by running the ezpgenerateautoloads= .php as shown in the example below: =20 cd /<ezpublish-5-root-dir>/ezpublish_legacy/ php bin/php/ezpgenerateautoloads.php=20 Generate eZ Publish .yml configuration To generate yml configuration for the new Symfony stack a console comman= d has been provided to cover single site setups. Perform the following command where <group> represent= s the siteaccess group name which will be created for your configurations i= n ezpublish.yml, for instance package name like "ezdemo_= site", "ezwebin_site" or "ezflow_site". An= d <admin_siteaccess> represents your admin siteaccess, f= or instance, "ezdemo_site_admin": =20 cd /<ezpublish-5-root-dir>/ php ezpublish/console ezpublish:configure --env=3Dprod <group> <= ;admin_siteaccess>=20 If you instead would like to manually create your yml config, do the fol= lowing: Copy ezpublish/config/ezpublish.yml.example to ezpub= lish/config/ezpublish_prod.yml Edit ezpublish/config/ezpublish_prod.yml