You can configure eZ Publish to store images, binary files and content-related caches in an Oracle database. This is typically useful if you want to run a site on a cluster of servers (refer to the "Clustering" section in the "Features" chapter of the eZ Publish Technical Manual for more information).

The following instructions explain how this can be done, assuming that you already have an eZ Publish site running on an Oracle database. The procedure consists of the following steps:

1. Updating eZ Publish files and clearing the caches
2. Modifying the "file.ini" settings
3. Creating a new script for serving images
4. Creating new database structures
5. Importing files to the database
6. Compiling the templates (optional)
7. Updating the Apache configuration
8. Restarting Apache and testing the site
9. Removing the imported files from the filesystem

These steps are very similar to the ones that are used when configuring eZ Publish to use clustering on a MySQL database, with a few differences in the first four steps, as described below.

1. Updating eZ Publish files and clearing the caches

Setting up the clustering feature for an eZ Publish site usually starts by clearing all caches and editing an override for the "file.ini" configuration file. However, if the site runs on an Oracle database, you have to update a few files in your eZ Publish installation before doing anything else. The following text describes how this can be done.

Navigate to the "extension/ezoracle/patches" directory and look for a subdirectory called "4.0.x", where "4.0.x" matches your current version of eZ Publish. Such a subdirectory contains the updated files for your version of eZ Publish. The directory structure under "extension/ezoracle/patches/4.0.x" maps to the path of the original files that must be replaced in your eZ Publish installation. You need to locate the corresponding files in eZ Publish, back them up and then replace them with the new ones provided by the extension.

If there is no subdirectory with a matching name, the updated files for your version of eZ Publish are not yet available. Therefore, it is not possible to set up clustering with your current version of eZ Publish at the moment.

Clearing the caches (optional)

It is recommended (but not required) to clear all eZ Publish caches before enabling the clustering functionality. This can be done by running the "bin/php/ezcache.php" script as shown below:

php bin/php/ezcache.php --clear-all --purge

After running the script, make sure that all cache files have been cleared by inspecting the contents of the various cache subdirectories within the "var" directory (typically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, remove them manually.

2. 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/ezwebin_site/file.ini.append.php" where "ezwebin_site" is the name of your siteaccess):

[ClusteringSettings]
FileHandler=ezdb
DBBackend=oracle
DBHost=
DBPort=
DBSocket=
DBName=ORCL
DBUser=scott
DBPassword=tiger
DBChunkSize=65535
ExtensionDirectories[]=ezoracle

Replace "ORCL", "scott" and "tiger" with the actual data:

• Name of the Oracle instance (usually a simple name specified in your "tnsnames.ora" file)
• User name
• Password

In most cases these values will be the same as the "Database", "User" and "Password" settings specified in the [DatabaseSettings] block of your "site.ini.append.php" configuration file.

The "DBHost", "DBPort" and "DBSocket" settings can be left empty, since they are not used when running eZ Publish on an Oracle database.

Setting the "FileHandler" configuration directive to "ezdb" will instruct eZ Publish to use the specified database for storing images, binary files and content-related caches. The "DBBackend" setting specifies the back-end to be used by the "ezdb" file handler. The "ExtensionDirectories" configuration array specifies the extension directories where eZ Publish should search for additional cluster file handlers and/or back-ends. The settings above will instruct eZ Publish to use the back-end located in "extension/ezoracle/clusterfilehandlers/dbbackends/oracle.php".

The "DBChunkSize" setting determines the size of the blocks (in bytes) into which files are split when they are fetched from the database.

3. 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',     'oracle'          );
define( 'STORAGE_USER',        'scott'           );
define( 'STORAGE_PASS',        'tiger'           );
define( 'STORAGE_DB',          'ORCL'            );
define( 'STORAGE_CHUNK_SIZE',  65535             );
 
include_once( 'index_image.php' );
?>

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

You must also copy the "index_image_oracle.php" file from the "extension/ezoracle" directory to the root directory of your eZ Publish installation.

4. Creating new database structures

You have to create some structures in the database manually. You'll find the needed definitions in the "oracle.php" file located in the "extension/ezoracle/clusterfilehandlers/dbbackends" subdirectory. The definitions are placed inside comment blocks in the beginning of the file.

When using the SQL*Plus command line tool, be sure not to miss the ending slash ("/") in the last line of the PL/SQL code copied from the "oracle.php" file.

5. Importing files to the database

Refer to the "Clustering - Setting it up" documentation page for details on steps 5-9.