During Step 4: Updating and redeploying individual websites of the deployment process, before the site is placed back online, Site Factory will run post-site-update hooks. These hooks are run with increased concurrency so are designed for scripts that take little processing themselves such as those that download data from external services. Heavy scripts, especially ones that communicate with the database, can exceed the available resources of Site Factory and cause site downtime. For most use cases, it is suggested to use a db-update hook.

Using the post-site-update hook

Follow Executing your commands with a hook to set up your hook. See the best practices for hook scripts. The scripts you create will be given Hook arguments similar to all other Site Factory hook scripts and one additional argument. The additional argument is the number of previous failed attempts of the script. The first run of the script will be given “0” for this argument.

In the event of a failure, post-site-update hooks are retried up to three times. Hook scripts are retried until they succeed and are not reran when any following scripts fail. To prevent further retries and abort the running of post-site-update hooks a script can return an exit code of 131 (ENOTRECOVERABLE).

The following is an example implementation of the hook. Customers are advised to do the required edits to this example to match the requirements of their Drupal application and Site Studio version. As with all hook scripts, the script file should be made executable before committing to the code repository.

#!/usr/bin/env bash
#
# Factory Hook: db-update
#
# Run cohesion commands after executing

SITEGROUP="$1"
ENVIRONMENT="$2"
DB_ROLE="$3"
DOMAIN="$4"
ATTEMPT="$5"

echo "Sitegroup: $SITEGROUP"
echo "Environment: $ENVIRONMENT"
echo "DB role: $DB_ROLE"
echo "Domain: $DOMAIN"
echo "Attempt: $ATTEMPT"

# Drush executable:
drush="/mnt/www/html/$SITEGROUP.$ENVIRONMENT/vendor/bin/drush"

# Create and set Drush cache to unique local temporary storage per site.
cache_dir="/mnt/tmp/$SITEGROUP.$ENVIRONMENT"

echo "Generated temporary Drush cache directory: $cache_dir."

echo "Initializing Acquia Site Studio tasks on $DOMAIN domain in $ENVIRONMENT environment on the $SITEGROUP application."

# Import cohesion (edit as needed).
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" /usr/local/php8.3/bin/php -d memory_limit=1024M $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN cohesion:import
result=$?

# Import cohesion package.
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" /usr/local/php8.3/bin/php -d memory_limit=1024M $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN sync:import --overwrite-all --force

# Rebuild cohesion.
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN cohesion:rebuild
# Clear the cache.
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" /usr/local/php8.3/bin/php -d memory_limit=1024M $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN cache:rebuild

# Clean up the drush cache directory.
echo "Removing temporary drush cache files."
rm -rf "$cache_dir"

set +v

# If a failure (non-zero) exit code is returned here, Site Factory will retry
# up to 3 times before treating this script as failed.  This behaviour can be
# overridden by returning exit code 131 to signal that this script has failed
# and no further retries should be attempted.
exit $result

After the implementation of this hook, the effects should be observable during the next code deployment process that updates site code and databases (a code-only update will show no effect). The effect can be seen in the task logs as an additional SitePostUpdate task corresponding to each of the usual SiteUpdate tasks. A SitePostUpdate task is created after completion of the corresponding SiteUpdate. Detailed logs for each of these tasks will show if the script is executing as expected.

Troubleshooting

If a script in the post-site-update directory ends with an error (a non-zero exit code), no additional scripts will run in the directory, and the task logs will display error messages in SitePostUpdate tasks.

post-site-update hook in Site Factory

#!/usr/bin/env bash
#
# Factory Hook: db-update
#
# Run cohesion commands after executing

SITEGROUP="$1"
ENVIRONMENT="$2"
DB_ROLE="$3"
DOMAIN="$4"
ATTEMPT="$5"

echo "Sitegroup: $SITEGROUP"
echo "Environment: $ENVIRONMENT"
echo "DB role: $DB_ROLE"
echo "Domain: $DOMAIN"
echo "Attempt: $ATTEMPT"

# Drush executable:
drush="/mnt/www/html/$SITEGROUP.$ENVIRONMENT/vendor/bin/drush"

# Create and set Drush cache to unique local temporary storage per site.
cache_dir="/mnt/tmp/$SITEGROUP.$ENVIRONMENT"

echo "Generated temporary Drush cache directory: $cache_dir."

echo "Initializing Acquia Site Studio tasks on $DOMAIN domain in $ENVIRONMENT environment on the $SITEGROUP application."

# Import cohesion (edit as needed).
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" /usr/local/php8.3/bin/php -d memory_limit=1024M $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN cohesion:import
result=$?

# Import cohesion package.
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" /usr/local/php8.3/bin/php -d memory_limit=1024M $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN sync:import --overwrite-all --force

# Rebuild cohesion.
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN cohesion:rebuild
# Clear the cache.
DRUSH_PATHS_CACHE_DIRECTORY="$cache_dir" /usr/local/php8.3/bin/php -d memory_limit=1024M $drush -r /mnt/www/html/$SITEGROUP.$ENVIRONMENT/docroot -l $DOMAIN cache:rebuild

# Clean up the drush cache directory.
echo "Removing temporary drush cache files."
rm -rf "$cache_dir"

set +v

# If a failure (non-zero) exit code is returned here, Site Factory will retry
# up to 3 times before treating this script as failed.  This behaviour can be
# overridden by returning exit code 131 to signal that this script has failed
# and no further retries should be attempted.
exit $result