Upgrading to 6.4

Warning

This documentation describes upgrading from 6.3.1 to 6.4. Upgrading directly from 6.3.0 is not supported.

Upgrade Steps

There are no breaking changes in this release, but due to internal changes in repository you will have to dump your data, upgrade the dump, and load it into the new version:

1. Setup new installation

  1. Download Enonic XP http://repo.enonic.com/public/com/enonic/xp/distro/6.4.3/distro-6.4.3.zip
  2. Setup new XP installations - (for all servers in your entire cluster if you have one)

Tip

Remember to update any startup scripts you might have to launch your new installation given a server restart

2. Move configuration

  1. Copy your $OLD_XP_HOME/config/ and deploy/ folders to the the new $NEW_XP_HOME/ (on all nodes)
  2. Remove the $NEW_XP_HOME/config/org.apache.felix.fileinstall-deploy.cfg file (To support UI-based application installation)

3. Migrate Data

Tip

Remember to backup your existing data before starting this step

  1. If possible - stop traffic to the servers to avoid new data coming in during this process, or stop the servers after dumping the data.
  2. Dump data from existing server. (dump). The dump will be created in $OLD_XP_HOME/data/dump/
toolbox.sh dump -a su:password -t 6.3.1-dump
  1. Upgrade the dump with a new XP installation. (upgrade).
toolbox.sh upgrade -d [path/to/OLD_XP_HOME]/data/dump/6.3.1-dump
  1. Start the new server(s)
  2. Copy the upgraded dump files from the old to the new server, place it in $NEW_XP_HOME/data/dump/. The folder will be named “6.3.1-dump_upgraded_6.4.0”
  3. Load the updated dump (load)
toolbox.sh load -a su:password -s 6.3.1-dump_upgraded_6.4.0

4. Install Apps (OPTIONAL)

This release supports installing applications globally, using the repository. Follow the steps below if you want to migrate your apps from file.

  1. Make sure the $XP_HOME/deploy folder of the new installation is empty
  2. Install the Applications that was in the $XP_HOME/deploy folder using the Applications UI tool, or install-app

New Project Structure (OPTIONAL)

Developers can update their application project structure to benefit from some of the new application development capabilities such as Admin Tools and Widgets, and align their applications for other future improvements,

  • move .../resources/site/assets/ to .../resources/assets/
  • move .../resources/site/services/ to .../resources/services/
  • move .../resources/site/lib/ to .../resources/lib
  • Optionally move .../resources/site/views/ to .../resources/views/ - this is an optional folder.

XP is backward compatible, and will scan for assets/ and services/ - initially on root, then in site. But only the first discovered folder will be used. For libraries, the lookup pattern for “require” will now include scanning parent folders with lib/ folders until reaching the resources/ folder.

NB! If you have used explicit require references i.e. “/lib/mylib” these files must now be moved to resouces/ root, or referenced relatively instead.

(NB! Applications with updated structure will require minimum XP version 6.4)