Path

ez.no / documentation / ez publish / technical manual / 4.x / installation / the setup wizard


Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

The setup wizard

This part of the 4.x documentation is for eZ Publish 4.0, only reference section is common for all eZ Publish 4.x versions as well as eZ Publish 5.x "LegacyStack", please select the version you are using for the most up to date documentation!

This section contains a comprehensive guide through the web based setup wizard of eZ Publish. The setup wizard is designed to ease the initial configuration of the system. It can be started using a web browser when the necessary installation steps (described in the previous sections) are completed. The setup wizard will automatically start the first time the "index.php" file (located in the root of the eZ Publish directory) is accessed/browsed.

The setup wizard does not store or modify any data before the final step; thus, it can be safely restarted by reloading the URL containing only the "index.php" part. The back button (located at the bottom) can be used to jump back to previous steps in order to modify settings. A typical setup cycle consists of 12 steps:

  1. Welcome page
  2. System check
  3. Outgoing E-mail
  4. Database choice (optional)
  5. Database initialization
  6. Language support
  7. Site selection
  8. Access method
  9. Site details
  10. Site security
  11. Site registration
  12. Finish

Note that some of the steps will be omitted when an eZ Publish bundle is being installed.

Welcome page

Setup wizard - step 1

Step 1: Welcome page


This is the initial page of the setup wizard. This step allows the user to select which language that will be used during the installation process. In addition, the wizard also checks the system configuration and displays a note if it is not optimal (in this case, an additional button called "Finetune" will be available at the bottom of the page).

The system automatically pre-selects one of the languages according to your browser's language settings. You can choose another language by selecting the desired language using the drop-down list. (The list of available languages is built using the INI files located in the "share/locale" directory).

After you click "Finetune" (if available), the wizard will load the "System finetuning" page, which contains information about configuration issues. The following screenshot shows an example of this page.

System finetuning

System finetuning

After you click "Next", the wizard will either load the "System check" page (if some critical issues need to be fixed) or the "Outgoing E-mail" page (if everything is okay).

System check

Setup wizard - step 2

Step 2: Issues


This page usually appears if critical issues/problems are detected. The setup wizard will display information about the issues that need to be fixed and suggestions describing how they can be fixed.

Issues

There may be several issues/problems. A suggestion to each problem is presented below the description of the problem itself. The setup wizard will probably suggest the execution of miscellaneous shell commands (in order to fix ownerships, permissions, etc.). These commands must be executed using a system shell. Simply copy the commands from the browser window and paste them into an open shell. The setup wizard will run the system check again when the "Next" button is clicked. The "System check" page will keep reappearing until all issues have been fixed (or ignored, see the next section). Once everything is okay, the setup wizard will display the next step.

Ignoring tests

Some issues/problems may be ignored using a checkbox labelled "Ignore this test". However, it is recommended to fix all issues rather than ignoring them.

Outgoing E-mail

Setup wizard - step 3

Step 3: Outgoing E-mail


eZ Publish uses E-mail to send out miscellaneous notices. This step is used to configure how eZ Publish delivers outgoing E-mail. There are two options:

  • Direct delivery through sendmail (must be available on the server)
  • Indirect delivery using an SMTP (Simple Mail Transfer Protocol) relay server

On Linux/UNIX: try to use sendmail; use SMTP if sendmail is unavailable. On Windows: use the SMTP setting.

Sendmail

Mail is delivered directly using the sendmail transfer agent. The agent must be running on the same host as the webserver is running on. The sendmail binary is usually available on most Linux/UNIX systems. If sendmail is not available then SMTP should be used.

SMTP

Mail is delivered through an SMTP server. At the minimum, the hostname of the SMTP server must be specified.

Database type

Setup wizard - step 4

Step 4: Database choice


The setup will automatically detect database support that has been made available for the PHP scripting engine. If both MySQL and PostgreSQL are supported, the database choice dialog will appear. If PHP is setup only to support one type of database, eZ Publish will automatically use it and thus the database choice dialog will not be displayed.

Note that if the MySQLi extension is enabled in PHP, the "MySQL Improved" option will be available on the list. If you are going to use a MySQL database, it is recommended to select "MySQL Improved" instead of "MySQL".

Database initialization

Setup wizard - step 5

Step 5: Database initialization


Information about the hostname of the server running the database engine, and a username/password combination needs to be provided. After you click "Next", if MySQL or MySQL Improved are used, the setup wizard will attempt to connect to the database. The setup will only continue if it is able to connect to the specified MySQL server with the specified username/password combination. PostgreSQL parameters are tested at a later stage during the setup wizard. (Note that even if the eZ Publish Extension for Oracle® Database is installed, the setup wizard will not let you use an Oracle database. The configuration must be done manually as described in the documentation of the database extension.)

Language support

Step 6: Language support

Step 6: Language support


This step allows the user to choose a language configuration for the site that is being installed. The setup wizard automatically pre-selects one of the languages according to your browser's language settings. Use the radio buttons to choose the default language (required), and the checkboxes to choose the additional languages (optional). All the selected languages will be added to the system and put on the list of prioritized languages. You will be able to use any of these languages for creating and translating your content after the setup wizard is finished.

Note that choosing the default language at this step will determine default language, system locale and the most prioritized language for your site. If you select for example "German" as default language, then both locale and default language will be set to "ger-DE", your administration interface will be translated into German, and this language will be recorded as the most prioritized one for your site. Languages can be reconfigured at any time (even when a site is up and running) using the administration interface.

Note that regardless of the selected language configuration, the site will be created using UTF-8 as the character set.

Site selection

Step 7: Site selection

Step 7: Site selection


This step allows the user to select one of the standard site packages. These packages are intended to provide basic examples mostly for the purpose of demonstration and learning. However, it is possible to use them as a basic framework which you can extend/tweak in order to make it suitable for a specific purpose. A demo site usually contains some artwork (images), CSS code, actual content and template files. The plain type should be used when starting from scratch.

The setup wizard automatically fetches the list of available site packages from remote and internal repositories and asks the user to choose one. The default remote repository is http://packages.ez.no/ezpublish/4.0. Note that it only contains the following three site packages:

Older site packages such as "News site", "Shop site" and "Gallery site" are currently not available for eZ Publish 4.

The wizard will automatically download the selected site package and all its dependent packages, import them to the system and display a list of successfully imported packages as shown in the following screenshot. (This step will be omitted if all these packages are already stored under internal repositories.)

The list of imported packages

The list of imported packages

All dependent packages except for the site style package will be automatically installed.

Package language options

Package language options

Package language options

If the language configuration selected at the "Language support" step doesn't match the languages used in the packages being installed, the "Package language options" interface will appear as shown on the screenshot above. For example, the "Website interface" site package makes it possible to have demo content created in 2 languages: English (United Kingdom) and French. If the same languages are selected at the "Language support" step, the packages will be installed silently. Otherwise, the user will need to specify how the system should act towards the "superfluous" languages (i.e. languages that exist in the package but aren't present in the selected language configuration for the site). Possible actions are:

  • Skip content in this language
  • Create language (extend the language configuration of the site and create demo content in this language)
  • Map to another language (use demo data to create content in another language)

Dealing with possible problems

If the web server is not able to contact the remote repository (due to firewall rules for example), the setup wizard will display an error message at the "Site selection" step. To fix this, allow outbound connections to http://packages.ez.no in your firewall (port 80) or download the packages manually.

Outbound connections via proxy

If you allow only outbound connections via a proxy server, then you need to configure eZ Publish in the following way:

  1. Create a file called "site.ini.append.php" in the "settings/override" directory and make sure it contains the following lines:

    [ProxySettings]
    ProxyServer=proxy.example.com:3128
    User=myuser
    Password=secret
    

    Replace "proxy.example.com:3128" with the actual address and port number that can be used to access the web through the proxy server. If the proxy server requires authentication, you will also need to provide a valid username/password combination.

  2. Restart the setup wizard.

Note that CURL support must be enabled in PHP, otherwise outbound connections via proxy will not work.

Manual download of packages

If the wizard fails to connect the external packages repository, you can manually download the desired site package and all the dependent packages it requires and then upload/import them via the setup wizard. The following instructions reveal how this can be done.

  1. Go to the packages download page. The "Sites" section of this page contains the list of available site packages including the following information for each of them:

    • Name
    • Description
    • Dependencies (if any)

    Click on the name of the desired site package to download it. (A package is downloaded as an ".ezpkg" file.)

  2. Download all the dependent packages required by this site package (these are listed under "Dependencies"). You can download a package by clicking on its name. The packages are downloaded as ".ezpkg" files.
  3. Use the package import interface located at the bottom of the page in the setup wizard to upload/import the downloaded site package (click the "Choose" button, select the downloaded ".ezpkg" file that contains the site package and click the "Upload" button). The imported site package will appear on the list.
  4. Upload/import all the dependent packages using the same import interface.

Note: it is also possible to download packages manually from the remote repository. The following instructions reveal how this can be done.

  1. Go to the packages repository, find the desired site package and download it manually. (A package is downloaded as an ".ezpkg" file.)
  2. Unpack the ".ezpkg" file into a temporary folder and view the "package.xml" file in order to figure out which dependent packages are required (these are listed between the <dependencies> and </dependencies> XML tags as described here). Download all the dependent packages that are required.

Additional functionality

In eZ Publish 3.7 and earlier versions, the setup wizard included one more step called "Site functionality" that allowed to select additional features that should be installed. This step is no longer used. Additional functionality can be added after the setup wizard is finished by downloading the desired packages from the "Content objects" section of the packages download page, importing the packages and installing them.

Access method

Setup wizard: step 8

Step 8: Site access configuration


This step allows the configuration of the access method that should be used when eZ Publish receives a request. There are three options:

  • URL
  • Port
  • Hostname

URL

When the URL access method is used, eZ Publish selects the site that should be accessed based on the contents of the URL (in particular the part that comes right after "index.php"). This is the default and most generic option. It doesn't require any additional configuration. Use this setting when installing eZ Publish for the first time.

Port

When the port access method is used, eZ Publish selects the site that should be accessed based on a port number that is specified in the URL. The port number must be appended to the hostname of the web server: "http://www.example.com:81/index.php". This option requires additional web server and firewall configuration. Use this setting only if you know what you're doing.

Hostname

When this access method is used, each site is assigned a unique hostname. For example, "www.example.com" and "admin.example.com" can be assigned to the public and the administration interface respectively. This option requires additional web and DNS server configuration. Use this setting only if you know what you're doing.

Site details

Setup wizard - step 9

Step 9: Site details


This step allows the modification of settings related to the site that is being installed. Note that the "User path" and "Admin path" access values depend on which access method you choose. When the port access method is used these values are port numbers. If you use the URL access method then "User path" and "Admin path" should only contain letters, digits and underscores. If the hostname access method is used then some additional symbols like dashes, dots and colons are allowed whereas underscores aren't.

The available databases will be displayed in the database drop-down menu. The "Refresh" button can be used to update the list (if a database is being created at this point). It is required that the database uses UTF-8 as character set.

If the selected database already contains data, the "Site Details" page will reappear and ask what to do. Possible actions are:

  • Leave the data and add new
  • Remove existing data
  • Leave the data and do nothing
  • I've chosen a new database

Use the last option if another database has been chosen.

Site security

Setup wizard: step 10

Step 10: Site administrator


This step suggests some basic modifications that should be carried out in order to secure the site being installed. The suggested security tweak protects the configuration files from unwanted access. Don't worry about this unless you're setting up a site for public use.

Note that the administrator's username (login) is set to "admin" by default and can not be changed. If you need another username for site administrator, you can install eZ Publish, create a new administrator user, log in as this user and remove the old one.

Site registration

Setup wizard: step 11

Step 11: Site registration


This step allows you to control whether the setup should send an information E-mail to eZ Systems or not. The information will be used internally for statistics and for improving eZ Publish. No confidential data will be transmitted and eZ Systems will not misuse or sell these details. The following information will be sent:

  • System details (OS type, etc)
  • The test results
  • The type of database that is being used
  • The name of the site
  • The URL of the site
  • The languages that were chosen

Finished

Setup wizard: step 12

Step 12: Finished

The setup wizard has finished, eZ Publish is ready for use. Click on one of the links to access the various interfaces (public site, administration interface, etc.).

Note that it is possible to restart the installation wizard after its successful finishing by specifying "CheckValidity=true" in the "settings/override/site.ini.append.php" file so that the setup wizard will be initiated when trying to access the site.

Balazs Halasy (14/01/2005 12:18 pm)

Ricardo Correia (17/04/2013 9:57 am)

Julia Shymova, Svitlana Shatokhina, Geir Arne Waaler, Ricardo Correia


Comments

  • Access to User and Admin site

    Hello,
    I missed to save the page or note down URL of USER SITE and ADMIN SITE. How can I access them now?
    Thanks,
  • dont exist

    ... to restart the installation wizard after its successful finishing by specifying "CheckValidity=true" in the "settings/override/site.ini.append.php" file so that the setup wizard will be initiated when trying to access the site-

    Exactlly, this is my problem, my Ez installation is succesfully but when i access to home, the installation wizard start another time.

    In my ftp dont exist this file settings/override/site.ini.append.php

    ¿?¿?¿?¿?¿?¿?¿? what can i do ?¿?¿?¿?¿?¿?

    thanks

    congratulations by this excelent cms-
  • help

    hello
    i unzipped ez files into an directory of my pesonal site, this directory is called ez

    i called the url http://www.hor848.com/ez/index.php (hor848.com is my personal site)
    and i've got:
    Parse error: syntax error, unexpected ',', expecting '(' in /web/htdocs/www.hor848.com/home/ez/index.php on line 121

    someone kow why??
    many many thx


    • Re: help

      I received the same error and found out that i used PHP 4, so i updated to PHP5.
      This solved the problem!
  • Database

    My host is 1and1. I have several mysql databases. My problem is, on the database initialization, i'm not asked which database to use i.e:


    Servername:
    Port:
    Username:
    Password:
    Socket (optional):
    database: <<<<<<(missing)

    So when i get to the stage of site access, i'm presented my username as the database of choice. For my, the Username & Database name are different.
    As a result, i can't install ezpublish.
    How can i resolve this problem?
    • Re: Database

      Step 5 ("Database initialization") is where you tell the wizard how to connect to the database server. The wizard will display the available databases and suggest you to choose one during step 9 ("Site details").

      • Re: Re: Database

        I get the same error when choosing either MySQL or MySQL Improved... does not look like the instructions.
  • AcceptPathInfo On

    I have started to install eZ Publish on to my host server. When set english as default language i go to next step i get error notice:

    You need to enable AcceptPathInfo in your Apache config file, if you're using apache 2.x. If you're running apache 1.3, eZ Publish will not run in CGI mode.

    Check the Apache documentation, or enter the following into your httpd.conf file.
    AcceptPathInfo On

    My host has Apache 2.x but i can't edit httpd.conf file because i don't have access to it. I got answer from my host provider that i can do the same thing with .htaccess file but i do not know how to do that. I have tried all the options already and now i ask you for help!

    Thank you
    • Re: AcceptPathInfo On

      Hi, please post your question to http://ez.no/developer/forum Thank you!
  • Install Error

    I am getting the error below after clicking on last screen where data is inserted in MySQL and site is initialized. When I click on refresh after this error, I get 2 errors -
    EZSW-004
    Failed inserting data to mysql
    Table 'ezapprove_items' already exists
    EZSW-040
    Failed to initialize site package 'ezwebin_site'

    Error I get after providing all details and passing through the installation steps.
    ========================================================

    Server error!

    The server encountered an internal error and was unable to complete your request.

    Error message:
    Premature end of script headers: php-fcgi-starter

    If you think this is a server error, please contact the webmaster.

    Error 500

    creditacademy.info
    Tue Dec 23 15:50:00 2008
    Apache
    • Re: Install Error

      Same problem here. Did you already come up with the solution for this?
  • site details

    i am having troubles on instalation:

    Warning
    The database [monteiro_portal] cannot be used, the setup wizard wants to create the site in [utf-8] but the database has been created using character set [iso-8859-1]. You will have to choose a database having support for [utf-8] or modify [monteiro_portal] .

    What do I have to do?
    • Re: site details

      I have the same problem here. I installed MySQL administrator and can't connect to database.
      • Re: Re: site details

        The same on me ""the setup wizard wants to create the site in [utf-8] but the database has been created using character set []. "
  • Where can I find the admin interface ??

    In Site details i write:
    Tittle : My Site Name
    Site URL : http://www.MySiteName.com
    User Path: my_site_name
    Admin Path: my_site_Name_admin

    But In Finished I see:
    URL: User Site (Link=Eng) Admin site (Link= my_site_name_admin)

    The links go nowhere.

    Try the URL given in an answer above (Try - Log in to the administration interface of eZ publish: http://mysite.com/intranet/index.php/plain_site_admin), with the word "intranet" and it is not. But I can not log in to the administration interface of eZ publish.

    Where can I find the admin interface : http://ez.no/var/doc/storage/imag...r/14645-3-eng-GB/view_folder_doc.png

    Please help.

    Thanks



  • Database Initialization Error

    Server: hosted
    Port: 3306
    Type: MySQL

    When adding the database details, I get the following error message:



    Fatal error: Class 'ezcBaseOptions' not found in /homepages/46/d218878200/htdocs/iranbusinessjournal/kernel/private/options/ezpextensionoptions.php on line 54
    Fatal error: eZ Publish did not finish its request

    The execution of eZ Publish was abruptly ended, the debug output is present below.


    I have tried this with Improved MySQL and had same error message!

    Any idea?
  • db utf error

    I am getting an error that indicates "the setup wizard wants to create the site in [utf-8] but the database has been created using character set [iso-8859-1]" however in my db manager console it indicates "MySQL charset: UTF-8 Unicode (utf8)" which would seem to indicate I have it set up the way it is supposed to be but ez is not recognizing it. I have tried both the MySQL and the MySQL improved options and they both get stuck on this same error.
    • Re: db utf error

      Same here. And i have utf-8 db.
  • Site Security htaccess message

    Here is what I get:


    Site security

    Your site is not running in a virtual host mode, this is insecure. It is recommended to run eZ Publish in virtual host mode. If you do not have the possibility to use virtual host mode, you should follow the instructions below about how to install an .htaccess file. The .htaccess file tells the web server to restrict the access to certain files.

    If you have shell access, you can run the following commands.

    cd /hsphere/local/home/dante22e/givespamachance.com/spamville
    cp .htaccess_root .htaccess

    If you do not have shell access, you will have to copy the file using an FTP client or ask your hosting provider to do this for you.

    ----

    help.

    My web hosting service is useless and I can't understand what to do. I have WebShell editor to play with the files/folders.
    • Re: Site Security htaccess message

      LOL did I just post info that can harm me? I'm tired. I wonder if the comments above can be deleted? admin?
  • Installation Error

    Hello
    I uploaded ALL file of eZ publish 4.3 to my host server.
    when I start the installation i get the following:
    Fatal error: Class 'eZPersistentObject' not found in /home/training/public_html/ez/kernel/classes/ezsection.php on line 37
    Fatal error: eZ Publish did not finish its request
    The execution of eZ Publish was abruptly ended, debug information can be found in the log files normally placed in var/log/*

    Any comments!