#Migrate to Serenity (SaaS)
Learn more about Akeneo’s SaaS offering (Serenity)
If you are using Enterprise Edition for either an On-Premise or a Flexibility (PaaS) instance, your instance can be migrated to Serenity!
All upgrades to Serenity require Akeneo PIM v7
. If you are on an earlier version, you will need to upgrade to v7
before migrating to Serenity.
Instructions for upgrading a major version can be found in our article How to upgrade to a major version?
#What to expect
Your PIM’s URL will not change if you are migrating a Flexibility (PaaS) instance
If you have multiple instances (ex: testing, staging, and production), each instance needs to be migrated individually
This can give you a chance to run tests before your production instance is migrated
There is no need to manually update your PIM — all product feature and security updates are done automatically
There will be some downtime as we migrate your instance to Serenity
We will work with you to minimize the business impact of this downtime
#Before you begin
#Check that your project terms include Serenity
To avoid any delays in migrating your Akeneo PIM to our most advanced cloud offering, please contact your Customer Success Manager to ensure they are aware of your migration and that your project terms include Serenity.
If any changes need to be made, your CSM can work with you to amend the terms.
#Check that your PIM is on the latest patch
If you are not on the latest patch, you may encounter problems that can delay your migration to Serenity. To avoid any problems,
compare your PIM version (ex: 7.0.123
) with the latest version of Akeneo PIM.
To check if you need to upgrade, you can scroll to the bottom of your PIM’s UI —
if the PIM can be upgraded, you will see a message like Version: EE 7.0.20 Buckwheat | New patch available: v7.0.29
.
Guides to update the PIM to latest patch can be found here: How to apply a patch?
#Check your file structure
The file structure should be identical to the original PIM file structure.
There should not be any symbolic link inside the PIM’s file structure. If there are symbolic links in your PIM’s file structure, we require you to remove them and restore all PIM directories to their original locations.
The symbolic links might be related to:
Release directories
Shared asset directories
etc.
The PIM files should be inside the ‘pim’ directory at the root of
/home/akeneo
Any custom, temporary, or backup directories must be removed from
/home/akeneo
, as they will not be migrated to Serenity.
#Check your storage
Please note that only the files from directories that have been set up in the filesystem adapter will be migrated.
To make sure all media and uploaded file locations can be migrated, you must reference the location properly in config/packages/prod/oneup_flysystem.yml
oneup_flysystem:
adapters:
asset_storage_adapter:
local:
location: '%kernel.project_dir%/[path/to/asset/directory]'
catalog_storage_adapter:
local:
location: '%kernel.project_dir%/[path/to/catalog/directory]'
jobs_storage_adapter:
local:
location: '%kernel.project_dir%/[path/to/jobs/directory]'
archivist_adapter:
local:
location: '%kernel.project_dir%/[path/to/archivist/directory]'
data_quality_insights_shared_adapter:
local:
location: '%kernel.project_dir%/[path/to/data_quality_insights_shared/directory]'
tailored_import_storage_adapter:
local:
location: '%kernel.project_dir%/[path/to/tailored_import/directory]'
category_storage_adapter:
local:
location: '%kernel.project_dir%/[path/to/category/directory]'
local_storage_adapter:
local:
location: '/'
catalogs_mapping_adapter:
local:
location: '%kernel.project_dir%/[path/to/catalogs_mapping/directory]'
#Backup your PIM
We strongly advise you to make a MySQL backup of your data before you begin the migration process.
To do so, please follow the directions in our System Administration & Services Management documentation.
#Disable custom code
Serenity does not support custom code within the PIM. Serenity does support customization, but any customizations use API connections and apps from the App Store (this includes custom apps).
If you have custom code bundles, please remove them before you begin the migration process.
If you cannot find a suitable replacement for your custom code, please contact your Customer Success Manager — they may be able to suggest changes or offer solutions that are compatibile with Serenity.
#The migration process
#Open a Support ticket
To begin the process to migrate from an On-Premise or Flexibility instance to a Serenity instance, you will need to open a ticket with Akeneo Support.
When creating your Support ticket, please fill out the Help Desk form with the fields listed below:
Contact us about |
Akeneo PIM & Hosting |
What can we help you with? |
I’m in need of a service |
Environment |
Akeneo Flexibility (PAAS) or On Premise (self hosted or 3rd party host) |
Operation Type |
Flexibility > Migrate to Serenity or On Premise > Migrate to Serenity |
Please include the output of the commands below, preferably as plain text-formatted attachments so that we can begin working on your migration request. We cannot validate your instance’s migration to Serenity without all of the following information. If we request any changes, we may ask you to run some commands again to check the updated status of your PIM.
#Check the custom attribute removal
We need to make sure you do not have any custom attribute type stored in Assets, Reference Entities or Attributes. Thus, we require you to send us the results of the following shell commands:
$ bin/console pim:installer:check-attributes
$ bin/console akeneo:reference-entity:check-attributes
$ bin/console akeneo:asset-manager:check-attributes
#Check your database schema
Please send us the results of the following shell commands so that we can ensure your database schema is up-up-to-date and compatible with a migration.
We use /home/akeneo/pim
to refer to the default path to the PIM installation throughout this guide. If you are using an On Premise installation, your path may be different.
$ cd /home/akeneo/pim
$ bin/console pimee:database:inspect -f --env=prod
$ bin/console pimee:database:diff --env=prod
$
$ bin/console doctrine:migrations:status
$
$ bin/console doctrine:migrations:list
If the results of bin/console doctrine:migrations:status
show a non-zero number of “New” migrations, your
database may not be up to date. Please run bin/console doctrine:migrations:migrate
, run the status
and list
commands again,
and send us the output of all of these commands so that we can see any changes.
#Check your Elasticsearch version
Please send us the results of the following command so that we can ensure your Elasticsearch indexes can be migrated correctly:
$ bin/console pim:update:check-requirements
#Check your filesystem
We also require the output of the following commands, so that we can check to make sure your filesystem adapter is set up correctly for the migration to Serenity.
$ cd /home/akeneo/pim
$ bin/console debug:config OneupFlysystemBundle
#Schedule a timeslot for migration
The Akeneo Support team must validate the output of the above commands before we can schedule any migration.
Once we have received all of this information and validated it, we can schedule the Serenity migration operation with our Cloud Engineering team. Their hours are Monday to Friday, 9:00 am to 6:00 pm CET, excluding French public holidays. Please provide at least 48 hours notice between your request and the actual migration time slot. This gives our team time to prepare and to ensure that your migration runs smoothly.
For most instances, migrations will take between 2 and 4 hours. However, the duration of individual migration operations can vary — especially if your catalog is very large or complex.
If you have concerns about the timing of a migration, please let us know in the migration Support ticket and we will work with you to find the best solution.
When choosing a timeslot to schedule your migration, please keep in mind that your PIM will not be available while we migrate the data and set up your Serenity instance.
Given our Cloud team’s schedule, please let us know the best time to migrate (if it is not available, we will suggest alternate time slots).
Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!