Information for: DEVELOPERS   PARTNERS

Upgrading to Acquia Content Hub 8.x-2.x with Content Hub Upgrade Console

Overview

Content Hub Upgrade Console (CHUC) is a console-based tool, which helps Acquia Content Hub 8.x-1.x customers to upgrade to the latest version 2.x. Apart from upgrading, it also provides auditing, troubleshooting and fleet-wide commands to Content Hub customers.

See Evaluating Acquia Content Hub 8.x-1.x deployment before upgrading to Acquia Content Hub 8.x-2.x before proceeding to upgrade to Acquia Content Hub 8.x-2.x.

Important

  • Ensure that you have a separate Content Hub account for each environment. Otherwise you risk purging the entire subscription while testing in your non-production environments.

  • If you use Acquia Content Hub 8.x-1.x to syndicate content throughout a fleet of sites with multiple publishers and subscribers, this upgrade is strongly recommended. Otherwise, if you exclusively use Acquia Content Hub to enable Acquia Personalization, Acquia recommends that you do not upgrade to Acquia Content Hub 8.x-2.x.

    This typically means if you use Content Hub for syndication and not Personalization, an upgrade is recommended.

    Contact your Acquia account representatives or Acquia Support if you need help determining your use of Acquia Content Hub.

Requirements

  • PHP 7.3 or later
  • Acquia Cloud or Acquia Site Factory as a platform
  • If using Acquia Personalization, ensure that you are using the Acquia Lift module 4.x
  • A working Acquia Content Hub 8.x-1.x setup. Acquia Content Hub 8.x-1.x code should have the depcalc module code as well.
  • A working Acquia Content Hub 8.x-2.x code branch or tag, ready to deploy. The codebase should have the diff module. This is optional and can be removed after the upgrade process is complete.
  • Any configurations related to Content Hub that are stored in code need to be transferred to the database. CHUC will update those configurations.

Performing an upgrade

Note

To perform a Acquia Content Hub 8.x-1.x to Acquia Content Hub 8.x-2.x upgrade, ensure that you are running the most recent version of Acquia Content Hub, that is, 8.x-1.49 or later. Also, ensure that you are upgrading to Content Hub 8.x-2.21 or later.

  1. Ensure that the environment you are planning to upgrade is currently operational.

    For example, stage down production site to the dev environment and ensure that Acquia Content Hub 8.x-1.x is working in the dev environment.

  2. From your local computer, navigate to the location where acquia/contenthub-console is installed and create a platform:

    ./vendor/bin/commoncli platform:create
    

    This will ask you for credentials to Acquia Cloud or Acquia Cloud Site Factory for any sites you’d like to upgrade. Note that you should add all applications to the platform you create so the upgrade process happens on all of the relevant applications across your Content Hub fleet of sites in the environment specified.

    Note

    There are three platforms available in Acquia Content Hub: Acquia Cloud, Acquia Cloud multi site, Acquia Cloud Site Factory.

  3. Run the following command to start the upgrade:

    ./vendor/bin/commoncli ach:upgrade:start @platform_alias
    

    This command will walk you through all of the necessary steps to upgrade to Acquia Content Hub 8.x-2.x. @platform_alias should be the alias you created when running the ./vendor/bin/commoncli platform:create command.

Upgrade stages and troubleshooting

The following stages represent each step in the process of upgrading. Most stages are performed automatically by the tool outside of the manual deployment step after stage 3.

Stage 0: Performs an audit of the current platform

What does it do?

  • Prompts for credentials for the Acquia Content Hub subscription
  • Ensures that the Acquia Lift module version is 4.x, if you have Acquia Personalization installed
  • Audits the following:
    • Acquia Content Hub 8.x-1.x hook implementations
    • Missing UUIDs
    • Known issues with temporary files
    • The depcalc module
    • Synchronization of Acquia Content Hub settings overwrites
    • Existence of stream wrappers on this site
    • Valid SSL certificates

What if something goes wrong?

  • Ensure that your platform has been set correctly by running the following command:

    /vendor/bin/commoncli platform:describe
    
  • If any of the audits find a problem, it is important to fix the issue. Some issues can be fixed by CHUC while others will need to be fixed manually. These are known problems that the Content Hub Console is attempting to prevent prior to the Acquia Content Hub 2.x upgrade.

Stage 1: Generates service and database backups

What does it do?

  • Generates database backups of the sites in a platform
  • Generates a service backup

What if something goes wrong?

  • Database backups are generated using the Acquia Cloud and Acquia Cloud Site Factory API. If there’s a problem encountered while generating the database backups, contact your TAM or Acquia support.
  • If a problem happens during the generation of Content Hub Service backups, contact Acquia support.

Stage 2: Purges subscription and delete webhooks

What does it do?

  • Purges all of the entity data in the Content Hub service. Entity data will be re-exported in a later stage of the upgrade process.

What if something goes wrong?

  • If the Service has no entities, you may see a message that the purge failed. To fix this, export at least one entity in Acquia Content Hub 8.x-1.x and retry this step.
  • If the subscription cannot be purged due to another error, file a support ticket with Acquia.

Stage 3: Prepares upgrade command

What does it do?

  • Prepares the sites to be upgraded.

What if something goes wrong?

  • Ensure that the platform details are correct.

Manual step: Deploy Acquia Content Hub 8.x-2.x to the platform

Run the following composer commands on your 8.x-1.x codebase to get the necessary modules installed:

composer remove acquia/content-hub-php
composer remove depcalc
composer remove drupal/acquia_contenthub
composer require drupal/acquia_contenthub:~2
composer require drupal/diff

After running the composer commands above, commit the code to your Acquia-hosted repository and deploy the branch.

What does it do?

  • This is a manual step to deploy a Acquia Content Hub 8.x-2.x branch to the codebase on each site in the platform.
  • The Console will tell you to perform this step, but it cannot do it for you.

What if something goes wrong?

  • Follow the normal deployment workflow set forth by your development team.
  • Failures in code deployments should be discussed with your technical teams and/or Acquia Support.

Stage 4: Runs publisher upgrade command

What does it do?

  • Upgrades all of the publisher sites by running a drush command.

What if something goes wrong?

  • Ensure that your platform has been set correctly.

Stage 5: Creates scheduled jobs for publisher/subscriber queues

What does it do?

  • This creates the scheduled jobs (cron jobs) for Content Hub operations on the given platform.
  • Scheduled jobs are created using the Acquia Cloud or Acquia Cloud Site Factory APIs.

What if something goes wrong?

Contact Acquia Support if there’s a failure to create the scheduled job.

Stage 6: Validates the publisher queues

What does it do?

  • This checks to see whether queues on the sites have correct counts.
  • It also checks to ensure that the status of exported entities in the publisher tracking table are correct.

What if something goes wrong?

  • If the publisher has a lot of entities to export then it will keep waiting until all the entities have been published and the count reaches zero. Only then it will proceed to the next step. If it can’t continue, it means that the publisher queue is running. If the publisher queue is not running, then you must manually check it and resolve the issues.

Stage 7: Runs subscriber upgrade command

What does it do?

  • Upgrades all of the subscriber sites by running a drush command.

What if something goes wrong?

  • Ensure that your platform has been set correctly.

Stage 8: Enables Unsubscribe module if there are imported entities with local changes/auto-update disabled

What does it do?

  • Ensures that if entities were “disconnected” from Content Hub in 1.x, the same entities will stay “disconnected” in 2.x.

What if something goes wrong?

  • Contact the Content Hub team if there’s a failure during this stage.

Stage 9: Validates the upgraded subscription

What does it do?

  • This validates that the queues and the subscriber tracking table appear to be correct.

What if something goes wrong?

  • Manually correct the database tables.

Stage 10: Validates that default filters are attached to webhooks and all filters have been upgraded

What does it do?

  • Every Content Hub webhook has a default filter to prevent all content from importing. This ensures that the filter is set.
  • This also does a check to ensure that the database filters in 1.x have all been upgraded to cloud filters in 2.x.

What if something goes wrong?

  • Filters can be manually created if needed.
  • Contact the Content Hub team if there are other issues.

Stage 11: Validates the interest list

What does it do?

  • This validates that the entities in the tracking table(s) on the sites matches the interests in the service (which is the Content Hub Service’s way to know what entities are of interest to a webhook).

What if something goes wrong?

  • If there’s a mismatch, it can be manually corrected via drush commands.
  • Contact the Content Hub team as this should be a simple audit.

Available commands

After the package has been added to your application, you can list all commands available by running:

./vendor/bin/commoncli

Here are the two most relevant commands for upgrade:

Create a platform:

./vendor/bin/commoncli platform:create

Start the upgrade:

./vendor/bin/commoncli ach:upgrade:start @platform_alias