EZP-27142: Update migration guide for 1.11 and legacy bridge #28
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,28 +1,23 @@ | ||
| # Coming to eZ Platform from eZ Publish Platform | ||
|
|
||
| eZ Publish Platform (5.x) was a transitional version of the eZ CMS, bridging the gap between the earlier generation called eZ Publish (sometimes referred to as *legacy*), and the current eZ Platform and eZ Platform Enterprise Edition for Developers. | ||
|
|
||
| eZ Publish Platform introduced a new Symfony-based technology stack that could be run along the old (*legacy*) one, this bridging is still possible using something called Legacy Bridge, an optional package for eZ Platform. This fluid change allows eZ Publish users to migrate to eZ Platform in two steps, using the bridging as an intermediary stepping stone. | ||
|
|
||
| ## Upgrading eZ Publish Platform 5.4.x (Enterprise-) / 2014.11 (Community-edition) to eZ Platform v1.11 or higher | ||
|
|
||
| !!! caution "Things to be aware of when planning a migration" | ||
|
|
||
| 1. While the instructions below are fully supported, we are aware that the community, partners and customers come from a wide range of different versions of eZ Publish, some with issues that do not surface before attempting a migration. That's why we and the community are actively gathering feedback on Slack and/or support channels for Enterprise customers to gradually improve the migration scripts and instructions. Reach out before you start so others who have done this before you can support you. | ||
|
|
||
| 1. As of eZ Platform v1.11, Legacy Bridge is a supported option for 1.x and future 2.x series. This means you can plan for a more gradual migration if you want, just like you could on eZ Publish Platform 5.x, with a more feature-rich version of eZ Platform and (with 2.x) also more recent version of Symfony. This is a great option for those who want the latest features and are comfortable with more frequent releases. | ||
|
|
||
| 1. Additionally there are some other topics to be aware of for the code migration from eZ Publish to eZ Platform: | ||
|
|
||
| - [Field Types reference](../guide/field_type_reference.md) for overview of Field Types that do and don't exist in eZ Platform | ||
| - eZ Platform RichText Field Type capabilities, currently not covering [Custom Tags](https://jira.ez.no/browse/EZP-25357) | ||
| - Symfony 2.8, this is also the case on later 5.4.x versions, but not the first ones including 2014.11 | ||
| - API changes. While we have a strict backwards compatibility focus, some deprecated API features were removed and some changes where done to internal parts of the system. See [ezpublish-kernel:doc/bc/changes-6.0.md](https://github.com/ezsystems/ezpublish-kernel/blob/v6.7.0/doc/bc/changes-6.0.md) | ||
|
|
||
| !!! note | ||
|
|
||
|
|
@@ -38,14 +33,14 @@ This section describes how to upgrade your existing eZ Publish Platform 5.4 | |
| ## Check for requirements | ||
|
|
||
| - Information regarding system requirements can be found on the [Requirements documentation page](../getting_started/requirements_and_system_configuration.md); notable changes include: | ||
| - PHP 5.6, 7.0 or higher | ||
| - MariaDB or MySQL 5.5 or higher _(Postgres possible for upgrades, but not yet supported by the installer for new installations)_ | ||
| - Browser from 2016 or newer for use with eZ Platform backend UI | ||
| - This page assumes you have composer installed on the machine and that it is a somewhat recent version. See [About Composer](../getting_started/about_composer.md). | ||
|
|
||
| ## Upgrade steps | ||
|
|
||
| ### Step 1: Extract latest eZ Platform/Enterprise 1.11 or higher installation | ||
|
|
||
| The easiest way to upgrade the distribution files is to extract a clean installation of eZ Platform / eZ Enterprise to a separate directory. | ||
|
|
||
|
|
@@ -67,11 +62,16 @@ Assuming you have own composer packages *(libraries and bundles, but not eZ Publ | |
|
|
||
| Adapt the command with your `vendor`, `package`, version number, and add `"–dev"` if a given package is for dev use. Also check if there are other changes in `composer.json` you should move over. | ||
|
|
||
| ###### 2.2.2 Install XmlText Field Type | ||
|
|
||
| While no longer bundled, the XmlText Field Type still exists and is needed to perform a migration from eZ Publish's XmlText to the new docbook-based format used by the RichText Field Type. If you plan to use Legacy Bridge for a while before migrating content, you'll also need this for rendering content with XMLText. From `<new-ez-root>` execute: | ||
|
|
||
| `composer require --no-update "ezsystems/ezplatform-xmltext-fieldtype:^1.3.0"` | ||
|
|
||
| !!! note | ||
|
|
||
| As of v1.3, be aware this Field Type now uses the [Content View system] introduced in eZ Platform 1.0, so make sure you adapt custom templates and override rules if you plan to use this for rendering content _(in Legacy Bridge setup)_. | ||
|
|
||
|
|
||
| ##### 2.3. Config | ||
|
|
||
|
|
@@ -108,23 +108,58 @@ To move over your own custom configurations, follow the conventions below and ma | |
|
|
||
| ##### 2.4. Bundles | ||
|
|
||
| Move over registration of _your_ bundles you have from src and from composer packages, from old to new kernel: | ||
|
|
||
| `<old-ez-root>/ezpublish/EzPublishKernel.php => <new-ez-root>/app/AppKernel.php` | ||
|
|
||
|
|
||
| ##### 2.5. Optional: Install Legacy Bridge | ||
|
|
||
| If you don't plan to migrate content directly to newer eZ Platform Field Types, you can optionally install Legacy Bridge and gradually handle code and subsequent content migration afterwards. For installation instructions see [here](https://github.com/ezsystems/LegacyBridge/blob/master/INSTALL.md). | ||
|
|
||
| !!! note | ||
|
|
||
| The Legacy Bridge integration does not have the same performance, scalability or integrated experience as a pure Platform setup. Like on eZ Publish Platform 5.x there are known edge cases where, for instance, cache or search index won't always be immediately updated across the two systems using the bridge. This is one of the many reasons why we recommend a pure Platform setup where that is possible. | ||
|
|
||
|
|
||
| ###### 2.5.1 Setup symlinks for legacy folders | ||
|
|
||
| As eZ Publish legacy is installed via composer, we need to take care about placing some files outside it's generated `<new-ez-root>/ezpublish_legacy/` folder, and for instance use symlink to place them inside on install. | ||
|
|
||
| 1. For design & settings files that you'd typically would want to version in GIT, you can now take advantage of Legacy Bridges bultin symlink convention for this. So as installation already hinted about, you can generate structure and setup symlinks using `app/console ezpublish:legacy:symlink -c`, this will create folders you can use below in `<new-ez-root>/src/legacy_files/`. | ||
|
|
||
| 2. Same goes for `<new-ez-root>/ezpublish_legacy/var/[<site>/]storage` folder, however as this is typically not versioned in git it's no predefined convention for this. If you create a folder within your project structure for symlinking into this folder, as opposed to a mount somwhere else, just make sure to mark folder you create for this as ignored by git once the folder and corresponding `.keep` file has been added to your checkout. Example below will assume `<new-ez-root>/src/legacy_files/storage` was created for this purpose, if you opt for something else just adjust instructions. | ||
|
|
||
| ###### 2.5.2 Upgrade the legacy distribution files | ||
|
|
||
| The easiest way to upgrade the distribution files is to copy the directories that contain site-specific files from the existing 5.4 installation into "/<ezplatform>/ezpublish_legacy". Make sure you copy the following directories: | ||
| - `<old-ez-root>/ezpublish_legacy/design/<your_designs>` => `<new-ez-root>/src/legacy_files/design/<your_designs>` | ||
| - _Do NOT include built-in designs: admin, base, standard or admin2_ | ||
| - `<old-ez-root>/ezpublish_legacy/design/<your_designs>` => `<new-ez-root>/src/legacy_files/design/<your_designs>` | ||
|
There was a problem hiding this comment. nitpick? this line seems to be duplicated |
||
| - `<old-ez-root>/ezpublish_legacy/settings/siteaccess/<your_siteaccesses>` => `<new-ez-root>/src/legacy_files/settings/siteaccess/<your_siteaccesses>` | ||
| - `<old-ez-root>/ezpublish_legacy/settings/override/*` => `<new-ez-root>/src/legacy_files/settings/override/*` | ||
| - Other folders to move over _(or potentially setup symlinks for)_ if applicable: | ||
| - ezpublish_legacy/var/storage/packages | ||
| - ezpublish_legacy/extension/* _(do NOT include the built-in / composer provided ones, like: ezflow, ezjscore, ezoe, ezodf, ezie, - ezmultiupload, ezmbpaex, ez_network, ezprestapiprovider, ezscriptmonitor, ezsi, ezfind)_ | ||
| - ezpublish_legacy/config.php & ezpublish_legacy/config.cluster.php | ||
|
|
||
| !!! note | ||
|
|
||
| Since writable directories and files have been replaced / copied, their permissions might have changed. You most likly need to reconfigure webserver user permissions as instructed further down. | ||
|
|
||
| ##### 2.6 Binary files | ||
|
|
||
| Binary files can simply be copied from the old to the new installation: | ||
|
|
||
| `<old-ez-root>/web/var[/<site_name>]/storage => <new-ez-root>/web/var[/<site_name>]/storage` | ||
|
|
||
| !!! note | ||
|
|
||
| In the eZ Publish Platform 5.x install `web/var` is a symlink to `ezpublish_legacy/var`, so if you can't find it in path above you can instead copy the storage files to the similar `ezpublish_legacy/var[/<site_name>]/storage` path. | ||
|
|
||
| ##### 2.7 Re-apply permissions and update composer | ||
|
|
||
| Since writable directories and files have been replaced / copied, their permissions might have changed. Re-apply permissions as explained in [the installation instructions](../getting_started/install_manually.md#setup-folder-rights). | ||
|
|
||
| When that is done, execute the following to update and install all packages from within `<new-ez-root>`: | ||
|
|
||
|
|
@@ -134,7 +169,7 @@ When that is done, execute the following to update and install all packages from | |
|
|
||
| At the end of the process, you will be asked for values for parameters.yml not already moved from old installation, or new *(as defined in parameters.yml.dist)*. | ||
|
|
||
| ##### 2.8 Register EzSystemsEzPlatformXmlTextFieldTypeBundle | ||
|
|
||
| Add the following new bundle to your new kernel file, `<new-ez-root>/app/AppKernel.php`: | ||
|
|
||
|
|
@@ -144,27 +179,27 @@ Add the following new bundle to your new kernel file, `<new-ez-root>/app/AppKern | |
|
|
||
| ##### 3.1. Execute update SQL | ||
|
|
||
| Import to your database the changes provided in one of the following files. It's also recommended to read inline comments as you might not need to run some of the queries: | ||
|
|
||
| `MySQL: <new-ez-root>/vendor/ezsystems/ezpublish-kernel/data/update/mysql/dbupdate-5.4.0-to-6.11.0.sql` | ||
|
|
||
| `Postgres: <new-ez-root>/vendor/ezsystems/ezpublish-kernel/data/update/postgres/dbupdate-5.4.0-to-6.11.0.sql` | ||
|
|
||
| ##### 3.2. Once you are ready to migrate content to Platform Field Types | ||
|
|
||
| Steps here should only be done once you are ready to move away from legacy and Legacy Bridge, as the following Field Types are not supported by legacy. In other words, content you have migrated will not be editable in legacy admin interface anymore, but rather in the more modern eZ Platform backend UI, allowing you to take full advantage of what the Platform has to offer. | ||
|
|
||
| ###### 3.2.1 Migrate XmlText content to RichText | ||
|
|
||
| **If** you are ready to migrate your eZ Publish XMLText content to the eZ Platform RichText format and start using pure eZ Platform setup, you can use a script to migrate content from the XmlText format to the new RichText format. Execute the following from <new-ez-root>: | ||
|
|
||
| `php app/console ezxmltext:convert-to-richtext -v` | ||
|
|
||
| The command example suggests using the verbose flag. This is optional, but recommended as we are actively gathering feedback on how it works with older eZ Publish content, and on how we can improve it both [via issues in the repository](https://github.com/ezsystems/ezplatform-xmltext-fieldtype), and on Slack. | ||
|
|
||
| ###### 3.2.2 Migrate Page field to Landing Page (eZ Platform Enterprise only) | ||
|
There was a problem hiding this comment.
|
||
|
|
||
| **If** you use Page field (ezflow) and a eZ Enterprise subscription, and are ready to migrate your eZ Publish Flow content to the eZ Platform Enterprise Landing Page format. You can use a script to migrate your Page content to Landing Page, to start using a pure eZ Platform Enterpise setup. See [Migrating legacy Page field (ezflow) to Landing Page (Enterprise)](#migrating-legacy-page-field-ezflow-to-landing-page-enterprise) for more information. | ||
|
|
||
| ### Step 4: Re-configure web server & proxy | ||
|
|
||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nitpick: "were done" instead of "where done"