Acquia

Acquia is a cloud hosting platform for Drupal applications, with managed infrastructure and developer tools.

This page is for the lead or DevOps engineer who runs a project built from Vortex on Acquia. It explains what happens on Acquia during a deployment, how the site detects its environment and how to run the routine operations. For general Acquia documentation, see the Acquia documentation.

Acquia deploys from a Git repository of its own, so CI builds the codebase and pushes it there. Artifact deployment covers that part.

Integration

The following sections describe what the integration does on Acquia.

Tasks

Vortex gives you the following tasks on Acquia:

• Fetch a database from an Acquia environment for local development or CI
• Copy the database between Acquia environments, for example to refresh staging from production
• Copy files between environments to synchronize uploaded content
• Purge the Varnish cache so visitors see fresh content

These tasks read the application name (VORTEX_ACQUIA_APP_NAME) from your .env file and the Acquia Cloud API credentials (VORTEX_ACQUIA_KEY and VORTEX_ACQUIA_SECRET) from .env.local.

Deployment automation

On each code deployment, Vortex runs these steps on Acquia:

1. Provisions the site: runs database updates, imports configuration, rebuilds caches and runs Drupal's deploy hooks (drush deploy:hook)
2. Purges the Varnish edge cache to serve fresh content
3. Notifies configured channels about the deployment

The steps run as Acquia Cloud Hooks: scripts in the hooks/ directory that Acquia runs on code deployments, code updates and database copies.

The scripts live in hooks/library/. hooks/common/post-code-update/ holds numbered symlinks to provision.sh, purge-cache.sh and notify-deployment.sh. The post-code-deploy and post-db-copy directories are symlinks to post-code-update. A code deployment, a code update and a database copy therefore run the same 3 steps. hooks/prod/post-code-deploy/ holds no scripts, and any you put there run in production after the common ones.

Acquia runs the scripts in hooks/common/<event>/ first, then those in hooks/<environment>/<event>/. The environment directory takes the environment's name, such as dev, test or prod. The event is a hook such as post-code-deploy or post-db-copy. When a script exits with an error, Acquia skips the remaining scripts and marks the task as failed. The task log shows the output of every hook that ran.

The provision hook adds drush/php-ini to PHP_INI_SCAN_DIR, so Drush commands run with the project's PHP settings from that directory.

The hooks read their settings from Acquia environment variables. Add them in the Acquia Cloud UI under Variables, for every environment or for selected ones.

To turn a hook off, set its skip variable to 1 in the Acquia UI:

Hook	Variable
provision.sh	VORTEX_PROVISION_ACQUIA_SKIP
purge-cache.sh	VORTEX_PURGE_CACHE_ACQUIA_SKIP
notify-deployment.sh	VORTEX_NOTIFY_ACQUIA_SKIP
copy-db.sh	VORTEX_TASK_COPY_DB_ACQUIA_SKIP
copy-files.sh	VORTEX_TASK_COPY_FILES_ACQUIA_SKIP

copy-db.sh and copy-files.sh sit in hooks/library/, and no event directory links them. By default they copy from prod into the environment the hook runs in. To run them, symlink them into an environment directory, for example hooks/dev/post-code-deploy/, and keep them out of common, where prod would copy onto itself. A linked script must keep its executable bit. copy-db.sh also needs VORTEX_TASK_COPY_DB_ACQUIA_NAME, the name of the database to copy.

A hook stops with an error when a value it requires is unset or empty. A blank field in the Acquia UI counts as empty. purge-cache.sh and both copy hooks require VORTEX_ACQUIA_KEY and VORTEX_ACQUIA_SECRET, so set both in the Acquia UI before the first deployment.

purge-cache.sh purges the domains listed in hooks/library/domains.txt. The installer writes your domain there as $TARGET_ENV_REMAP.<domain>. Add a line for every other domain the site serves.

$TARGET_ENV_REMAP expands to dev on dev, stage on test and test2 on test2. On prod, the prefix and its dot are removed. Any other environment, including on-demand ones, purges nothing.

notify-deployment.sh builds the notification URL from Acquia's AH_SITE_NAME and AH_REALM variables: https://<site>.<realm>.acquia-sites.com. To use a custom domain, such as www.example.com, set VORTEX_NOTIFY_ENVIRONMENT_DOMAIN in the Acquia UI.

Environment detection

Vortex detects Acquia by its AH_SITE_ENVIRONMENT variable and then applies the settings in web/sites/default/includes/providers/settings.acquia.php. That file includes Acquia's own settings file and maps the Acquia environment to an environment type. prod becomes production, and stage and test become staging. Every other environment, including on-demand ones, becomes development.

The same file also sets these platform settings:

• It points the configuration sync directory at DRUPAL_CONFIG_PATH or Acquia's config_vcs_directory.
• It turns on automatic .htaccess creation in writable directories.
• It sets the temporary file path.
• It delays the initial database connection by turning off Acquia's acquia_hosting_settings_autoconnect setting.

Acquia settings file

By default, Vortex includes the Acquia-provided settings file from /var/www/site-php/{group}/{group}-settings.inc, where {group} is the value of AH_SITE_GROUP. To use another file, set the DRUPAL_ACQUIA_SETTINGS_FILE environment variable to its path. If the file doesn't exist, Drupal stops with an error. When AH_SITE_GROUP is empty, Vortex includes no settings file.

Temporary file path

Vortex sets the path for temporary files (file_temp_path) from 3 sources, each one overriding the one before it:

1. Default: /tmp
2. Shared GFS mount: when DRUPAL_TMP_PATH_IS_SHARED is 1, the path is /mnt/gfs/{group}.{env}/tmp, a directory on Acquia's shared file system, mounted on each web head. Use it for operations such as bulk uploads, which need a temporary directory shared across web heads. See Acquia temporary files documentation for details.
3. Explicit override: a non-empty DRUPAL_TMP_PATH wins over both.

Onboarding

Acquia onboarding is part of the project setup flow. See Set up hosting in the Installation guide and select Acquia.

Routine operations

The following sections cover the operations you run against Acquia environments.

Fetch database

To fetch a database backup from your Acquia environment for local development or CI builds, run the following command:

ahoy fetch-db

When the database source (VORTEX_FETCH_DB_SOURCE) is acquia, the installer's default for Acquia projects, the command downloads the latest Acquia backup. The command takes the VORTEX_FETCH_DB_ACQUIA_DB_NAME database from the VORTEX_FETCH_DB_ENVIRONMENT environment, which is prod in the shipped .env. It reuses an existing local dump. To create a new backup and download it, add --fresh.

Run a hosting task

The vortex-task runner copies databases and files between environments and purges the edge cache. It passes each operation to the script for the configured hosting platform:

./vendor/bin/vortex-task <operation>

The following table lists the operations that Acquia supports:

Operation	Description
copy-db	Copy the database between environments
copy-files	Copy files between environments
purge-cache	Purge the edge (Varnish) cache

The runner also accepts a fourth operation, custom, which only Lagoon implements.

The runner reads the platform from VORTEX_PLATFORM, or from VORTEX_TASK_PLATFORM to override it for a single task. The Acquia hooks export VORTEX_PLATFORM themselves. To run an operation manually, for example from your local machine, set it yourself:

VORTEX_PLATFORM=acquia ./vendor/bin/vortex-task copy-db

Each operation reads the application name and API credentials from your .env and .env.local files. Outside the hooks, the operations have no default environments, so set them for a manual run:

• copy-db: VORTEX_TASK_COPY_DB_ACQUIA_SRC, VORTEX_TASK_COPY_DB_ACQUIA_DST and VORTEX_TASK_COPY_DB_ACQUIA_NAME (the database name).
• copy-files: VORTEX_TASK_COPY_FILES_ACQUIA_SRC and VORTEX_TASK_COPY_FILES_ACQUIA_DST.
• purge-cache: VORTEX_TASK_PURGE_CACHE_ACQUIA_ENV, plus VORTEX_TASK_PURGE_CACHE_ACQUIA_DOMAINS_FILE when the domain list isn't domains.txt in the current directory (the hook sets it to hooks/library/domains.txt).

For example, to copy the production database into dev, run the following command from the project root:

VORTEX_PLATFORM=acquia \
VORTEX_TASK_COPY_DB_ACQUIA_SRC=prod \
VORTEX_TASK_COPY_DB_ACQUIA_DST=dev \
VORTEX_TASK_COPY_DB_ACQUIA_NAME=your_site \
./vendor/bin/vortex-task copy-db

Replace your_site with the name of the Acquia database to copy.

Each operation also takes its own VORTEX_TASK_<OPERATION>_ACQUIA_KEY, _SECRET and _APP_NAME, where <OPERATION> is COPY_DB, COPY_FILES or PURGE_CACHE. They default to VORTEX_ACQUIA_KEY, VORTEX_ACQUIA_SECRET and VORTEX_ACQUIA_APP_NAME.

After Acquia starts the copy or the purge, the operation checks its status every 10 seconds, up to 600 times. To change those numbers, set VORTEX_TASK_<OPERATION>_ACQUIA_STATUS_INTERVAL and VORTEX_TASK_<OPERATION>_ACQUIA_STATUS_RETRIES, for example VORTEX_TASK_COPY_DB_ACQUIA_STATUS_INTERVAL. When the checks run out, copy-db and copy-files fail. purge-cache prints a warning and moves on to the next domain.

Confirm that a manual run finished. The last line of its output starts with [ OK ] Finished. For a database copy, the line reads [ OK ] Finished database copying between environments in Acquia. A failed run stops at a line that starts with [FAIL] and names the problem, for example [FAIL] Unable to copy database from prod to dev environment.

Run Drush against remote environments

To run Drush commands against Acquia environments, download your Drush aliases from the Acquia Cloud UI. See Using Drush aliases.