Information for: DEVELOPERS   PARTNERS   SUPPORT

Acquia CMS upgrade

The information in this section helps you upgrade your installed version of Acquia CMS.

The upgrade of Acquia CMS from v1.x to v2.x makes Acquia CMS a module instead of a profile. Acquia recommends that you upgrade from v1.x to v2.x to leverage the latest features of the composable architecture.

Important

The procedure on this page is tested. However, Acquia recommends that you back up your site’s database and configuration before proceeding.

Upgrading Acquia CMS from v1.x to v2.x

Acquia CMS v1.x is a profile and Acquia CMS v2.x is a module that keeps all the required dependencies previously available in the Acquia CMS v1.x profile.

To upgrade to Acquia CMS v2.x, you must remove the Acquia CMS profile. There is no official approach for this type of operation in the Drupal community.

To upgrade to Acquia CMS v2.x:

  1. To identify the current version of Acquia CMS that you are using, run the following command:

    $ composer show acquia/acquia_cms | grep 'versions'
    versions : * v1.4.11
    
  2. To upgrade Acquia CMS to the latest 1.5.x release, run the following command:

    $ composer update acquia/acquia_cms
    
  3. To verify the Acquia CMS version, run the following command:

    $ composer show acquia/acquia_cms | grep 'versions'
    versions : * v1.5.2
    
  4. To ensure Acquia CMS is updated with all the latest modules, run the following command:

    $ composer show  'drupal/acquia_cms*'
    drupal/acquia_cms_article     1.4.0 Provides an Article content type and related configuration.
    drupal/acquia_cms_audio       1.4.0 Provides an Audio media type and related configuration.
    drupal/acquia_cms_common      1.5.0 Handles shared functionality for Acquia CMS.
    drupal/acquia_cms_component   1.3.3 Provides component and related configuration for Acquia CMS.
    drupal/acquia_cms_document    1.4.0 Provides a Document media type and related configuration.
    drupal/acquia_cms_event       1.4.0 Provides an Event content type and related configuration.
    drupal/acquia_cms_image       1.4.0 Provides an Image media type and related configuration.
    drupal/acquia_cms_page        1.4.0 Provides an unstructured Page content type and related configuration.
    drupal/acquia_cms_person      1.4.1 Provides a Person content type, a structured data representation of people associated with a website or organization.
    drupal/acquia_cms_place       1.4.0 Provides a Place content type and related configuration.
    drupal/acquia_cms_search      1.4.2 Provides powerful search capabilities to the site.
    drupal/acquia_cms_site_studio 1.4.1 Handles code for Site Studio Installation & Related Configurations.
    drupal/acquia_cms_starter     1.3.3 Contains the example content for demonstration.
    drupal/acquia_cms_toolbar     1.4.0 Acquia CMS styling brought to admin toolbar.
    drupal/acquia_cms_tour        1.3.3 Provides a tour page for Acquia CMS.
    drupal/acquia_cms_video       1.4.0 Provides a Video media type and related configuration.
    
  5. If you are using BLT and drush status --fields=install-profile reports directly through the acquia_cms profile:

    1. Edit blt/blt.yml.
    2. Change the profile key to minimal.
  6. Run drush acms:switch to use the automated uninstall tool.

    This ensures safe uninstallation of Acquia CMS by making the necessary changes.

    $ ./vendor/bin/drush acms:switch
    The site's install profile will be switched from acquia_cms to minimal.
    
    Do you want to continue? (yes/no) [ yes ]:
    > yes
    
    Profile switched from acquia_cms to minimal.
    
  7. Verify the site and ensure that it works as expected.

  8. Export config.

  9. Commit all changes and deploy them to your dev, stage and production environments.

    You can observe the changes in the core.extension config.

    $./vendor/bin/drush cex
    [notice] Differences of the active config to the export directory:
    +----------------+----------------------------------------------------+-------------+
    | Collection     | Config                                             | Operation   |
    +----------------+----------------------------------------------------+-------------+
    |                | acquia_cms_common.settings                         | Create      |
    |                | core.extension                                     | Update      |
    |                | system.theme.global                                | Update      |
    |                | acquia_cms.settings                                | Delete      |
    +----------------+----------------------------------------------------+-------------+
    
    The .yml files in your export directory (../config/default/sync) will be deleted and replaced with the active config. (yes/no) [ yes ]:
    > yes
    

    Important

    The remaining steps must be deployed to dev, stage and production environments after completion of database updates and successful import of the configuration. At this point, your composer.json file must have acquia/acquia_cms profile. Otherwise, you are likely to get errors.

  10. After deployment, verify that everything works as expected.

  11. To upgrade Acquia CMS to the 2.x version, run the following command:

    $ composer require -W acquia/acquia_cms:^2.0
    

    Acquia CMS v2.x is a module that keeps all the required dependencies previously available in the profile.

  12. Verify that everything works as expected.