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.
Creating siteaccesses for dev and staging
In our case, in the dev and staging siteaccesses, we will create the following symbolic links from the eng folder siteaccess:
Open a shell, and in the eZ Publish installation folder, use the ln (link) command to create the new symbolic links from the existing siteaccess configuration file:
# cd setting/siteaccess
# ln -s eng/browse.ini.append.php dev/browser.ini.append.php
# ln -s eng/contentstructuremenu.ini.append.php dev/contentstructuremenu.
# ln -s eng/toolbar.ini.append.php dev/toolbar.ini.append.php
It is very important to execute the ln command for all of the files listed above, to ensure that the siteaccess will not inherit the settings from the default configuration files.
Creating symbolic links
Next, we have to create more symbolic links for the configuration files in the staging_panel and dev_panel folder. So we'll create them from the ezwebin_site_admin files.
This is the file list:
Use the same command as before, this time specifying the starting folder (ezwebin_site_admin):
# ln -s ezwebin_site_admin/browse.ini.append.php dev_panel/browser.ini.
We need to repeat this command for each file listed before.
Next, we will have to copy the following files from the eng folder to dev and staging. We have to copy these files because we will change them according to our needs.
We also need to copy the following files from the ezwebin_site_admin folder to dev_panel and staging_panel:
Configuring the database parameters
The last step is to configure the parameters related to the database connection for the staging and development installations, modifying all of the files named site.ini.append.php found inside the different siteaccess folders.
Open a shell and go to the eZ Publish installation folder. Then go into the settings/siteaccess folder and for each siteaccess that you have created, you need to edit the file site.ini.append.php, adding the following code, if it is not already present, at the top of the file:
As we create the siteaccesses, we have to add them to the site.ini.append.php file in the settings/override folder . Copy the following code into the file:
Creating multilingual siteaccesses
eZ Publish creates a siteaccess for every language that we enable. If we'd like to add more languages for our site, we need to create a new siteaccess folder and configure the language settings inside it.
Let's create, for example, a German siteaccess. This task can be summarized in the following three steps:
- Create a new folder called de, inside settings/siteaccess/.
- Copy the files or create the appropriate symbolic links as per the eng siteaccess, inside the de folder.
- Configure the siteaccess .ini configuration files for the language.
Copying the configuration file
We need to create all of the .ini files from the main language siteaccess in the new language folder (de). To do this, we need to create a symbolic link for all the files, except the site.ini.append.php, that are to be copied into the new folder.
Editing ini files for locale components
Configure all of the site.ini.append.php files for all of the languages siteaccesses, to enable the new German language.
To do this we will edit the files, adding the highlighted code:
# vi settings/siteaccess/eng/site.ini.append.php
Do the same for the site.ini.append.php files in the fre folder and the ita folder.
After that, we need to copy the eng/site.ini.append.php to our new folder, de, and edit it as follows:
The directive SiteLanguageList tells us the order in which the system will show the content for our objects. If the content isn't translated into German, eZ will show the English version; if the English version is unavailable than it will show the Italian one, and so on.
The last step is to add the new languages inside the settings/override/site.ini.append.php, as we did for the dev and staging siteaccesses:
Selecting a siteaccess using host or URI-based matching
eZ publish can work using host or URI-based access. Using the wizard, we selected the URI access method. This can be changed, if necessary, in the global override for the site.ini configuration file: /settings/override/site.ini.append.php. The behavior of the siteaccess system is controlled by the MatchOrder setting within the [SiteAccessSettings] block.
This is the default setting for the MatchOrder directive, and is set by the setup wizard. When this access method is used, the name of the siteaccess that we want to use has to be the first parameter that appears after the index.php part of the requested URL.
For example, the following URL will tell eZ publish to use the panel siteaccess: http://packmediaproject/index.php/panel. If we want to use the ita siteaccess, then the URL that we have to call will be http://packmediaproject/index.php/ita. If nothing is used in the last part of the URL, then the default siteaccess will be used.
Setting the default siteaccess
The default siteaccess is defined by the DefaultAccess setting within the [SiteSettings] section. To change it, we have to open the /settings/override/site.ini.append.php file and make the changes highlighted here:
The URI access method is very useful for the development/preview stage where changing the DNS server isn't very easy.
The host access method makes it possible to map different host/domain combinations to different siteaccesses. This access method requires the configuration of the server and DNS (not eZ Publish). The DNS server must be configured to resolve the desired host/domain combinations to the IP address of the web server, and then the web server must be configured to trigger a virtual host configuration (unless eZ Publish is located in the main document root). Once these settings are configured properly, eZ Publish can be set up to use different siteaccesses based on the host/domain combinations of the incoming requests.
The following example shows how to set up /settings/override/site.ini.append.php in order to make eZ Publish use the host access method. In addition, it reveals the basic usage of the host matching mechanism.
The example above tells eZ publish to use the eng siteaccess, if the requested URL starts with www.packmediaproject.com. If the requested URL starts with it.packmediaproject.com, the Italian version of the site will be used.
In the same way, we can configure HostMatchMapItems to use the admin panel and other languages. Using the host configuration is useful if we don't want to make the backend subdomain public, but want to make it internal to our network, or to support those sites that want to differentiate the languages instances with a dedicated subdomain.
In this article we learned what a siteaccess is, and how to configure and personalize it. We also learned how to add more languages to our sites, and how to change the access method from URL to Host mode.