Migrating Pimcore from on-premise to Pimcore PaaS

Important notes:

• Pimcore PaaS supports Pimcore starting from 2024.2
• Available Pimcore PaaS services and their supported versions are listed here

Preparing for your migration

• Assess the current infrastructure

  • List all components (Pimcore version, database, services) and make sure they are supported and available on Pimcore PaaS
  • Identify services, bundles or modules that may need special handling
  • Ensure your codebase is in Git since Pimcore PaaS requires Git as VCS

• Backup Everything

  • Create a full backup of the Pimcore codebase and filesystem
  • Backup and export your database
  • Backup and export assets and non versioned files (configs, classes, etc)

• Review Pimcore PaaS requirements

  • Ensure compatibility with Pimcore PaaS supported PHP/Pimcore versions (8.x / 11.x)
  • Identify all third-party services (e.g. Redis, Elasticsearch, Opensearch) used in the project
  • Assess disk space and performance requirements so that you can properly size your apps and services

Configuring Pimcore PaaS

• Go trough the Pimcore PaaS setup and add PaaS bundle to your project
• Configure your project console and project/env variables

Migration

• Codebase

  • Ensure your Git VCS code is ready to be pushed to your Pimcore PaaS remote. You add Pimcore PaaS remote trough project onboarding
  • Update configurations to match your performance requirements eq applications.yaml, services.yaml should be considered
  • Push your codebase to Pimcore PaaS remote

• Database

  • Import your DB export. Tip - You can connect directly to DB with your IDE using tunneling
  • Check if you need some additional handling in your DB (running some custom scripts or something)

• Files

  • Your app may include content files, meaning files that aren't intended to be part of your codebase so aren't in Git. You can upload such files to mounts you created. Upload to each mount separately.

    Upload to each of directories above by running the following commands ie:

    pimcore-cloud mount:upload --mount var/ --source ./var
    pimcore-cloud mount:upload --mount public/var --source ./public/var

  • If you are planning to do a storage type migration during your migration to PaaS check out this storage migration guide

Final touches

• Run the needed commands

  • After syncing data from local from /var/ and /public/var, ensure you are running rebuilding your classes:

     php bin/console pimcore:deployment:classes-rebuild --create-classes

  • After migrating DB and binaries clear cache

     php bin/console pimcore:cache:clear

  • Depending on your setup, you would likely need to run the following commands which are updating indices in OpenSearch and rebuild Alternative Element Trees:

    php bin/console datahub:simple-rest:create-or-update-mapping
    php bin/console datahub:simple-rest:init-index
    php bin/console advanced-object-search:update-mapping
    php bin/console advanced-object-search:re-index
    php bin/console generic-data-index:update:index 
    php bin/console bpt:aet:rebuild-tree -a
    php bin/console pimcore:maintenance

Testing and validation

• Test your app

  • Ensure the frontend and backend functionalities are working.
  • Test asset loading, object creation, and user sessions to verify the integrity of the migration.
  • Check your specific configurations

• Check and monitor logs

  • Review logs on Pimcore PaaS for any errors during migration

Go live

• Prepare your domain and dns records to point to your Pimcore PaaS
• Switch DNS to point to Pimcore PaaS once the migration is validated in a production environment.

Common Pitfalls

While we are trying to ensure as best possible experience during your migration, some pitfalls can encounter Here are some tips what they can be and how to overcome them

1. Unsupported PHP or Library Versions

   • Mismatch between Pimcore PaaS -supported versions and the ones currently in use. Ensure that the PHP version and dependencies are compatible. Update to latest versions where possible to make future updates faster.

2. Database Import Errors

   • Large datasets can sometimes cause issues during the import process, especially if timeouts occur. Use split dumps or staged imports for large databases.
   • If your DB dump contains DEFINER statements you would need to remove it, as its not supported on Pimcore PaaS

3. File Storage Differences

   • Pimcore PaaS uses a different file storage architecture than on-prem setups. File system is read only after the app has ben deployed, so you need to ensure Pimcore assets storage are correctly mapped and mounted afterwards.

4. Third-Party Service Configurations

   • Redis, Opensearch or some other services might require reconfiguration for Pimcore PaaS solution.
   • Validate that all services are properly connected and configured after migration.

5. Environment Variables Handling

   • Misconfigured environment variables could lead to issues.
   • Ensure your variables and secrets are correctly set per project and environment.