What is the siteaccess system?
To override eZ Publish’s default configuration, we need to create a collection of configuration settings called siteaccess. The role of a siteaccess is to indicate to eZ which database, design, and var directory should be used for a particular context.
With siteaccess it is possible to use the same content and different designs (for example, when creating a mobile version of our site) or do the opposite (for example, managing a multilingual site where the template doesn’t change but the content does).
It’s also possible to create an administration siteaccess, where we can manage any kind of content, such as users, media files and, of course, the articles, or a frontend siteaccess that is the website, where we can only view the public published content.
A typical eZ publish site consists of two siteaccesses: a public interface for visitors and a restricted interface for editors. In this case, both siteaccesses use the same content, but different designs. Whereas the administration siteaccess would most likely use the built-in administration design, the public siteaccess would probably use a custom design.
The following illustration, taken from the official eZ Publish documentation, shows this scenario:
Usually, in big projects it is also useful to have two additional siteaccesses: a staging siteaccess and a developing siteaccess. The first is used in a staging environment to make frequent deployments of modifications that can be tested by the customer (in this case, the siteaccess uses a different database but the same design as for the public and admin siteaccesses). The second one, instead, is used by developers on their local machine (this siteaccess uses a local database, but once again uses the same design as for the public and admin siteaccesses).
A single eZ publish installation can host a virtually unlimited number of sites by simply adding new siteaccesses, designs, and databases.
Siteaccess folder structure
The configuration settings for siteaccesses are located inside a dedicated subfolder within the /settings/siteaccess folder. The name of the subfolder is the actual name of the siteaccess.
It is very important to remember that a siteaccess name can only contain letters, numbers, and underscores.
The following illustration shows a setup with two siteaccesses: admin and public.
When a siteaccess is in use, eZ publish reads the configuration file in the following sequence:
- Default configuration settings: /settings/*.ini
- Siteaccess settings: /settings/siteaccess/[name_of_siteaccess]/*.ini.append.php
- Global overrides: /settings/override/*.ini.append.php
eZ Publish will first read the default configuration settings. Then, it will determine which siteaccess to use based on the rules that are defined in the global override for site.ini /settings/override/site.ini.append.php. When it knows which siteaccess has to be used, it will go into the correct siteaccess folder and read the configuration files that belong to that siteaccess. The settings of the siteaccess will override the default configuration settings.
For example, if a siteaccess uses a database called packtmediaproject_test, the system will find this and automatically use the specified database when an incoming request is processed.
Finally, eZ Publish reads the configuration files in the global override directory. The settings in the global override directory will override all other settings. So, if a database called packtmediaproject is specified in the global override directory for site.ini, then eZ publish will attempt to use that database regardless of what is specified in the siteaccess settings.
If a setting is not overridden either by the siteaccess, or from within a global override, then the default setting will be used. The default settings are set by the .ini files located in the /settings directory. The following figure illustrates how the system reads the configuration files, using the site.ini file as an example:
Creating a siteaccess for dev, staging, and production environments
Once we have finished installing eZ Publish, we’ll find a folder called setting/siteaccess, with the default siteaccess automatically configured.
In our case we’ll find these folders:
- admin: This folder usually isn’t used as siteaccess, but it contains a standard configuration file that can be used to set up the administration panel
- setup: This folder contains all of the configuration files that are used during the installation process
- ezwebin_site: This is where the main design is imported directly from the eZ.no site for the package eZ Webin
- ita, eng, fre: Last but not least, the ita, eng, and fre folders have the configuration files used by the site to enable internationalization and localization
The ezwebin_site_admin is created by the webmin site package, and contains all of the configuration files for the administration panel.
Enterprise siteaccess schema
In an enterprise development process, it is very important to have four more siteaccesses:
The siteaccesses dev and dev_panel will be used as a development playground installation, which can be used by the development team members, with their own configuration parameters, such as database connection, path, and debug file. This will help them to test different configuration parameters or extensions without impacting the production site.
The siteaccesses staging and staging_panel will be used as a staging arena that can be used by a customer to evaluate new functionality before it is released to production. Usually, the staging installation is installed on a clone of the production server, to make sure that everything works in the same way. In our case, we will work on the same server to better understand how to create the different siteaccesses.
All siteacccesses will have some configuration files in common, and sometimes these have to assign the same value to the parameters specified inside them. For example, if you need to create a new language siteacccess, you’ll need to copy the same module configuration files to be sure that they will work in the same way for all of the languages. In this case, it will be useful to create a symbolic link from one siteaccess to another. If you don’t know what a Linux symbolic link is, you can think of it as a virtual pointer to a real file, like a Windows XP shortcut.