Package

« 
Previous article
|
eZ
|
Next article
 »

Table of contents:

For a general description of package, we recommend Software package on Wikipedia.

What is a package?

An eZ publish package is used to distribute certain parts of an eZ publish installation to other eZ publish sites. These parts include content classes, content objects, site styles and extensions. The setup wizard also uses packages, the so-called "site packages".

File format

An eZ publish package file can be recognized by it's filename extension .ezpkg. Package files do not have their own MIME type, they are served as the default type application/octet-stream.

Actually a package is a gzipped tar file. The PHP zlib extension is required because it is used to compress and decompress eZ publish packages.

The package file contains a file called package.xml. This file contains the package definition in an XML dialect.

Package management

You can create, install, or remove packages with the online package manager or with the command line package manager.

Compatibility

"Based on my experience, packages between version don't work smoothly. I'd suggest to copy the db and do an update by hand with the provided mysql/postgres sql files + run the php if needed." -- X+

Tip: Package distribution, selection, downloading and installation

Remember that prior to the eZ Publish 3.8 release, packages were distributed within the ezpublish download source packages (tar.gz, zip) themselves.

After eZ Publish 3.8 release, these packages were further distributed to the installations on demand during the setup wizard package selection, download and import.

Tip: Avoiding package download and import errors within setup wizard using eZ Publish 3.8.0+ (or greater version)

The following advise applies to eZ Publish 3.8.0 through 4.6 (Community Build 2011.11)

Have you ever have trouble during the setup wizard package selection, downloading and importing of the default eZ Publish packages like eZ Flow, eZ Webin or others?

This issue in question seems to be reported most frequently by users who's internet server (web server for example) which is behind a restrictive firewall or proxy server. In short when eZ Publish because of PHP configuration, curl availability, or restricted internet access for the server to use making outgoing requests ... can not connect to the remote package server. 

If you do provide the web server with network access, php-curl or certain built-in PHP functions disabled, you must either solve the aforementioned problems or ... you must install packages using a local repository directory.

Did you know you can download these packages yourself from the Official eZ Systems' eZ Publish ezpkg package server, http://packages.ez.no/ezpublish/

Before using the setup wizard at all ... please perform the following steps with special attention to the specific details as they are key to solving this problem.

  1. Simply navigate to /path/to/ezpublish root directory.
  2. Download -all- the files (specifically index.xml and *.ezpkg file extension file name) in the package server's release directory (release version number) (IE:  '/4.6/4.6.0/') which corresponds to the version number of the copy of eZ Publish you are trying to setup using your own preferred method, yourself, from the Official eZ Systems' eZ Publish ezpkg package server, http://packages.ez.no/ezpublish/
    1. For example with eZ Community Build 2011.11 you will want to download all files (including the index.xml file) in found within the package server's release directory (release version number) (IE:  '/4.6/4.6.0/') into 'var/storage/packages/eZ-systems/' from this remote url, http://packages.ez.no/ezpublish/4.6/4.6.0
    2. Most users do not understand or realize the package names they require to complete setup normally which is why I recommend getting them all as you can repeat the process again more gracefully with all the packages and choose different setups as needed or desired.
    3. If your an eZ Publish expert, know the package management systems related, and know the package names your require then you can choose to download only the packages you know you need.
    4. No additional subdirectories are supported or allowed. If you use additional subdirectories (beyond the directory named the same as the package minus the extension '.ezpkg' with the contents of the package itself) your uncompressed packages will not be detected or imported from local sources.
    5. Do not simply mirror the the package server or more than one of it's directories as this directory structure is not supported at all with local package installation. The local package import directory should contain almost the same files as the remote version specific directory. 
    6. Again, make certain the web server (user and group) can read and write to all the files in the package directory.
  3. Extract all downloaded package files (*.ezpkg) -into- a new directory for each package (you must create this) with the same name as the package (without the '.ezpkg' file extension)
    1. IE: the ezwebin_site.ezpkg file extraction directory I would need to create would be called ezwebin_site
    2. Remember .ezpkg files are really just renamed tar.gz files in a very specific directory structure which must be maintained. You can use the gnu tar to extract the contents of the packages into directories with the same base name.
    3. You can use this simple bash script to extract the packages correctly within the above directory as current directory on Unix-like systems with the Bash shell it's called bcuncompressezpackages.sh
      1. You can get a copy of this script from GitHub, https://github.com/brookinsconsulting/bcuncompressezpackages
      2. If you don't want to check out the script using Git. Here is a direct link to the raw script, simply copy and paste into a file in the root ezpublish directory with the filename of 'bcuncompressezpackages.sh', https://raw.github.com/brookinsconsulting/bcuncompressezpackages/master/bin/shell/bcuncompressezpackages.sh
      3. To run the script simply first set it's file permissions, chmod 777 ./bcuncompressezpackages.sh;
      4. Then feel free to run the script. You must run the script for the eZ Publish root directory or it will fail. cd /path/to/ezpublish; ./bcuncompressezpackages.sh;
      5. Then feel free to continue with the following setup setup steps.
    4. If your concerned about file owner/group permissions you can optionally free yourself from any concerns in this regard by changing the package directories recursively file and group permissions to 777
    5. You'll thank yourself later when you have no setup problems that you assigned these permissions to these packages' directories.
  4. Re-start the setup wizard and complete the setup wizard normally. Local packages will be used to complete setup. It's painless and accurate.
    1. Packages should be installed from local sources using the local package directory after each request for the remote package file from the setup wizard to the remote package server fails (unavoidable, not visible or apparent behavior).
  5. Your done! Enjoy the time you saved, take a break, enjoy nature and a tall glass of orange juice!
    1. You can optionally remove the downloaded / original package (.ezpkg) files out of the 'var/storage/packages/eZ-systems/' directory as they are no longer required or you can leave them as they cause no harm and only consume disk space.
  6. Warning: While you can remove the actual compressed package files above as described we must be clear ... we -do not- recommend removing the uncompressed package directories or their contents as these files are expected to live here indefinitely as they represent part of the now installed packages in eZ Publish.

Did you know? Local package import/installation and setup wizard completion time is much faster than remote package import and installation during setup wizard!

Here is a related companion forum reference regarding this problem and this recently updated solution

Details about the setup wizard's behavior during package import and installation

It may also be worth mentioning here is the fact that even after failing to fetch the initial index.xml file from the remote package server, the setup wizard will continue to try to use the internet / remote package server regardless of the first (or continued) failure -or- the existence of local xml / remote packages in the correct directory at the correct time, etc. It always tries to use the package server first, then falls back to checking after each failure for a local copy (uncompressed) in the package dir mentioned above.

The setup wizard first it tries to use curl (if available/installed/detected/etc) to fetch the files from the remote package server and then falls back to try using to use built-in / core php functions and perform another attempt to connect using the different method. Now if either of those features also are not available (depending on your php configuration) you can get the same remote packages server connection errors as well.

The files which are fetched from the remote package server are first temporarily stored in 'var/cache/packages/' (using the same file name as found on the remote host) before being copied to 'var/storage/packages/eZ-systems/' directly. You may also wish to check the permissions of the 'var/cache/packages/' directory as if it is incorrect the remote package selection may fail.

These changes were introduced and released in eZ Publish 3.8. They were clearly documented in the provided feature documentation.

Tip: Avoiding package download and import errors within setup wizard using eZ Publish 3.x through 3.6.12

Have you ever have trouble during the setup wizard package selection and importing of the default eZ Publish packages?

You can replace the packages which are normally distributed with eZ Publish (3.x -> 3.6.12) release packages. This might help if you do not have these packages at this time and need to reinstall eZ Publish or simply re-run the setup wizard more specifically.

If you create the 'packages' directory in the root ezpublish directory and download the required packages into this directory before running the setup wizard you will install your packages via local sources.

In this way you may also be able to install custom packages here as well?

  1. Simply navigate to /path/to/ezpublish root directory.
  2. Create directory 'packages' in the root ezpublish directory.
  3. Change directory file and group permissions to 777
  4. You'll thank yourself later when you have no setup problems that you assigned these permissions to the 'packages' directory .
  5. Download the packages you require / design into the 'packages' directory directly using your own preferred method yourself
  6. Remember to only store *.ezpkg files in the 'packages' directory. No subdirectories are supported or allowed. If you use subdirectories your packages will not be detected or imported from local sources.
  7. You should not need to unpack the packages (up to eZ Publish 3.6.12)
  8. Again, make certain the web server (user and group) can read and write to all the files in the package directory.
  9. Start or re-start setup wizard and complete setup normally. Packages should be installed from local sources over remote sources.

Local packages installation is the standard for eZ Publish 3.x through 3.6.12 and setup wizard completion time was acceptable. The setup wizard performance improved over the years / releases and today is very fast indeed (even without using local package installation).

Solutions

External resources