Setting it up

The following instructions reveal how you can configure eZ publish to store images, binary files and content-related caches in the database.

1. Modifying the "file.ini" settings

Add the following lines to an override for the "file.ini" configuration file ("settings/override/file.ini.append.php" or "settings/siteaccess/shop_site/file.ini.append.php" where "shop_site" is the name of your siteaccess):

[ClusteringSettings]
FileHandler=ezdb
DBBackend=mysql
#DBBackend=pgsql
DBHost=localhost
DBPort=3306
DBSocket=
DBName=name
DBUser=user
DBPassword=pass
DBChunkSize=65535

Replace "localhost", "name", "user" and "pass" by actual host name, database name, user name and password (in most cases these values will be the same as "Server", "Database", "User", "Password" settings specified under the "[DatabaseSettings]" block of your "site.ini.append.php" configuration file). Make sure that the "DBSocket" setting value is correct (leave it empty if you have "Socket=disabled" under the "[DatabaseSettings]" block in "site.ini.append.php").

Specifying "ezdb" in the "FileHandler" configuration setting will instruct eZ publish to use the specified database for storing images, binary files and content-related caches. The "DBBackend" setting specifies which back-end that should be used by the "ezdb" file handler. The "DBChunkSize" setting determines the size of the blocks (in bytes) into which files are split when they are fetched from the database.

2. Creating a new script for serving images

All images (except design images) will be served by PHP. Apache will be instructed to use a specific PHP script called "index_cluster.php" for handling images. The script must include "index_image.php" along with a collection of configuration settings. This trick makes the serving of images faster because the system does not have to read the configuration from the database. Create the "index_cluster.php" inside the eZ publish root directory and make sure that it contains the following lines:

<?php
define( 'STORAGE_BACKEND',     'mysql'           );
define( 'STORAGE_HOST',        'localhost'       );
define( 'STORAGE_PORT',        3306              );
define( 'STORAGE_SOCKET',      ''                );
define( 'STORAGE_USER',        'user'            );
define( 'STORAGE_PASS',        'pass'            );
define( 'STORAGE_DB',          'name'            );
define( 'STORAGE_CHUNK_SIZE',  65535             );

include_once( 'index_image.php' );
?>

Make sure you specify the same database settings as indicated under the "[ClusteringSettings]" block in your "file.ini.append.php" configuration file.

3. Downloading missing files

If your eZ publish distribution does not contain "index_image_mysql.php" and "index_image_pgsql.php" files (this typically occurs in eZ publish 3.8.1 to 3.8.3 versions because of a bug in the build scripts), download them using the following links (deprecated):

• index_image_mysql.php
• index_image_pgsql

Put the downloaded files into the root directory of your eZ publish installation.

4. Creating new database tables

You have to create some tables in the database manually. You'll find the table definitions in the "mysql.php" or "pgsql.php" file (dependent on which database you use) located in the "kernel/classes/clusterfilehandlers/dbbackends" subdirectory. The definitions are placed inside comment blocks in the beginning of the files.

5. Importing files to the database

You need to copy the files stored in the "var" directory to the database. To do this, go to the root directory of eZ publish and launch the following script (replace "shop_site" by the actual name of your siteaccess):

$ bin/php/clusterize.php -s shop_site

The script will import your files, images and image aliases (image variations) that are stored under the "var" directory to the database.

6. Clearing the caches

To clear the cache that is stored on disk, go to the root directory of eZ publish and use one of the following commands:

$ bin/shell/clearcache.sh --clear-all
$ bin/shell/clearcache.sh --clear-all --var-subdir=shop_site

This is the last time you're using the "clearcache.sh" script since it is only capable of operating on the filesystem but not the database. To clear the caches from now on, use the administration interface or the "bin/php/ezcache.php" script.

7. Compiling the templates (optional)

Since all caches now are empty, you should re-compile the templates. Note that this step can be skipped and thus the templates will be compiled on-demand when the site is browsed. Go to the root directory of eZ publish and launch the script:

$ /usr/local/php/bin/php bin/php/eztc.php -s shop_site

Repeat this step for all siteaccesses that are in use.

8. Updating Apache virtual host configuration

Apache needs to know which PHP script to use when serving images. The script simply fetches the images from the database and serves them. Add the following rewrite rules to your Apache configuration file before the other/existing rules:

Rewriterule ^/var/([^/]+/)?storage/images-versioned/.*  /index_cluster.php  [L]
Rewriterule ^/var/([^/]+/)?storage/images/.*            /index_cluster.php  [L]

9. Restarting Apache

You need to restart the Apache web server and then the system should be up and running in cluster mode.