Updated Acquia settings.

AlexSkrypnyk · AlexSkrypnyk · commit 582b621c3102 · 2026-04-02T17:17:10.000+11:00
diff --git a/.vortex/docs/content/hosting/acquia.mdx b/.vortex/docs/content/hosting/acquia.mdx
@@ -47,6 +47,27 @@ settings from [`web/sites/default/includes/providers/settings.acquia.php`](https
 This includes Acquia-specific configurations for caching, file paths, and
 environment variables.
 
+#### Acquia settings file
+
+By default, Vortex includes the Acquia-provided settings file from
+`/var/www/site-php/{group}/{group}-settings.inc`. You can override this path
+by setting the `DRUPAL_ACQUIA_SETTINGS_FILE` environment variable.
+
+#### Temporary file path
+
+Vortex configures the temporary file path (`file_temp_path`) with a three-tier
+priority:
+
+1. **Default**: `/tmp`
+2. **Shared GFS mount**: If `DRUPAL_TMP_PATH_IS_SHARED` is set, uses
+   `/mnt/gfs/{group}.{env}/tmp` — a per-head mounted directory on Acquia's
+   shared filesystem. This is useful for operations like bulk uploads that
+   require a shared temporary directory across web heads. See
+   [Acquia temporary files documentation](https://docs.acquia.com/acquia-cloud-platform/manage-apps/files/temporary#section-important-considerations)
+   for details.
+3. **Explicit override**: If `DRUPAL_TMP_PATH` is set, its value is used
+   regardless of other settings.
+
 ## Onboarding
 
 Before you begin, ensure you have:
@@ -63,6 +84,9 @@ file:
 | Variable | Description |
 |----------|-------------|
 | `VORTEX_ACQUIA_APP_NAME` | Your Acquia application name (machine name) |
+| `DRUPAL_ACQUIA_SETTINGS_FILE` | Override the path to Acquia's settings `.inc` file (optional) |
+| `DRUPAL_TMP_PATH` | Override the temporary file path (optional) |
+| `DRUPAL_TMP_PATH_IS_SHARED` | Use Acquia's shared GFS mount for temporary files (optional) |
 
 For CI environments, configure these secrets in your CI provider ([GitHub Actions](/docs/continuous-integration/github-actions) or [CircleCI](/docs/continuous-integration/circleci)):
 
diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/web/sites/default/includes/providers/settings.container.php b/.vortex/installer/tests/Fixtures/handler_process/_baseline/web/sites/default/includes/providers/settings.container.php
@@ -15,10 +15,10 @@
 $vortex_localdev_url = getenv('VORTEX_LOCALDEV_URL');
 if (!empty($vortex_localdev_url)) {
   // Local development URL.
-  $patterns = str_replace(['.', 'https://', 'http://', ','], [
+  $container_patterns = str_replace(['.', 'https://', 'http://', ','], [
     '\.', '', '', '|',
   ], $vortex_localdev_url);
-  $settings['trusted_host_patterns'][] = '^' . $patterns . '$';
+  $settings['trusted_host_patterns'][] = '^' . $container_patterns . '$';
 
   // URL for internal container access (e.g., via drush, in tests etc.).
   $settings['trusted_host_patterns'][] = '^nginx$';
diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docroot/sites/default/includes/providers/settings.acquia.php b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docroot/sites/default/includes/providers/settings.acquia.php
@@ -15,22 +15,23 @@
 declare(strict_types=1);
 
 if (!empty(getenv('AH_SITE_ENVIRONMENT'))) {
+  $ah_site_group = getenv('AH_SITE_GROUP');
+  $ah_site_env = getenv('AH_SITE_ENVIRONMENT');
+
   // Delay the initial database connection.
   $config['acquia_hosting_settings_autoconnect'] = FALSE;
 
   // Include Acquia environment settings.
-  // The path is built dynamically from the AH_SITE_GROUP environment variable
-  // provided by Acquia Cloud.
-  $ah_site_group = getenv('AH_SITE_GROUP');
-  // @codeCoverageIgnoreStart
   if (!empty($ah_site_group)) {
-    $ah_settings_file = sprintf('/var/www/site-php/%s/%s-settings.inc', $ah_site_group, $ah_site_group);
+    $ah_settings_file = getenv('DRUPAL_ACQUIA_SETTINGS_FILE') ?: sprintf('/var/www/site-php/%s/%s-settings.inc', $ah_site_group, $ah_site_group);
+    // @codeCoverageIgnoreStart
     if (!file_exists($ah_settings_file)) {
       throw new \RuntimeException(sprintf('Acquia settings file "%s" not found. Check Acquia Cloud environment configuration.', $ah_settings_file));
     }
     require $ah_settings_file;
+    // @codeCoverageIgnoreEnd
   }
-  // @codeCoverageIgnoreEnd
+
   // Default all environments to 'dev', including ODE environments.
   $settings['environment'] = ENVIRONMENT_DEV;
 
@@ -51,14 +52,28 @@
   // Override the config sync directory with the DRUPAL_CONFIG_PATH environment
   // variable if provided, or fall back to the config_vcs_directory setting
   // provided by Acquia.
-  $drupal_config_path = getenv('DRUPAL_CONFIG_PATH');
-  if (!empty($drupal_config_path)) {
-    $settings['config_sync_directory'] = $drupal_config_path;
+  $config_path = getenv('DRUPAL_CONFIG_PATH');
+  if (!empty($config_path)) {
+    $settings['config_sync_directory'] = $config_path;
   }
   elseif (!empty($settings['config_vcs_directory'])) {
     $settings['config_sync_directory'] = $settings['config_vcs_directory'];
   }
 
   // Automatically create an Apache HTTP .htaccess file in writable directories.
   $settings['auto_create_htaccess'] = TRUE;
+
+  // Allow to override temporary path using per-head mounted directory or
+  // DRUPAL_TMP_PATH variable.
+  // @see https://docs.acquia.com/acquia-cloud-platform/manage-apps/files/temporary#section-important-considerations
+  $settings['file_temp_path'] = '/tmp';
+
+  if (!empty($ah_site_group) && getenv('DRUPAL_TMP_PATH_IS_SHARED')) {
+    // @see https://acquia.my.site.com/s/article/360054835954-Bulk-Upload-Not-Working-Correctly
+    $settings['file_temp_path'] = sprintf('/mnt/gfs/%s.%s/tmp', $ah_site_group, $ah_site_env);
+  }
+
+  if (getenv('DRUPAL_TMP_PATH')) {
+    $settings['file_temp_path'] = getenv('DRUPAL_TMP_PATH');
+  }
 }
diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docroot/sites/default/includes/providers/settings.container.php b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docroot/sites/default/includes/providers/settings.container.php
@@ -15,10 +15,10 @@
 $vortex_localdev_url = getenv('VORTEX_LOCALDEV_URL');
 if (!empty($vortex_localdev_url)) {
   // Local development URL.
-  $patterns = str_replace(['.', 'https://', 'http://', ','], [
+  $container_patterns = str_replace(['.', 'https://', 'http://', ','], [
     '\.', '', '', '|',
   ], $vortex_localdev_url);
-  $settings['trusted_host_patterns'][] = '^' . $patterns . '$';
+  $settings['trusted_host_patterns'][] = '^' . $container_patterns . '$';
 
   // URL for internal container access (e.g., via drush, in tests etc.).
   $settings['trusted_host_patterns'][] = '^nginx$';
diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docroot/sites/default/includes/providers/settings.acquia.php b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docroot/sites/default/includes/providers/settings.acquia.php
@@ -15,22 +15,23 @@
 declare(strict_types=1);
 
 if (!empty(getenv('AH_SITE_ENVIRONMENT'))) {
+  $ah_site_group = getenv('AH_SITE_GROUP');
+  $ah_site_env = getenv('AH_SITE_ENVIRONMENT');
+
   // Delay the initial database connection.
   $config['acquia_hosting_settings_autoconnect'] = FALSE;
 
   // Include Acquia environment settings.
-  // The path is built dynamically from the AH_SITE_GROUP environment variable
-  // provided by Acquia Cloud.
-  $ah_site_group = getenv('AH_SITE_GROUP');
-  // @codeCoverageIgnoreStart
   if (!empty($ah_site_group)) {
-    $ah_settings_file = sprintf('/var/www/site-php/%s/%s-settings.inc', $ah_site_group, $ah_site_group);
+    $ah_settings_file = getenv('DRUPAL_ACQUIA_SETTINGS_FILE') ?: sprintf('/var/www/site-php/%s/%s-settings.inc', $ah_site_group, $ah_site_group);
+    // @codeCoverageIgnoreStart
     if (!file_exists($ah_settings_file)) {
       throw new \RuntimeException(sprintf('Acquia settings file "%s" not found. Check Acquia Cloud environment configuration.', $ah_settings_file));
     }
     require $ah_settings_file;
+    // @codeCoverageIgnoreEnd
   }
-  // @codeCoverageIgnoreEnd
+
   // Default all environments to 'dev', including ODE environments.
   $settings['environment'] = ENVIRONMENT_DEV;
 
@@ -51,14 +52,28 @@
   // Override the config sync directory with the DRUPAL_CONFIG_PATH environment
   // variable if provided, or fall back to the config_vcs_directory setting
   // provided by Acquia.
-  $drupal_config_path = getenv('DRUPAL_CONFIG_PATH');
-  if (!empty($drupal_config_path)) {
-    $settings['config_sync_directory'] = $drupal_config_path;
+  $config_path = getenv('DRUPAL_CONFIG_PATH');
+  if (!empty($config_path)) {
+    $settings['config_sync_directory'] = $config_path;
   }
   elseif (!empty($settings['config_vcs_directory'])) {
     $settings['config_sync_directory'] = $settings['config_vcs_directory'];
   }
 
   // Automatically create an Apache HTTP .htaccess file in writable directories.
   $settings['auto_create_htaccess'] = TRUE;
+
+  // Allow to override temporary path using per-head mounted directory or
+  // DRUPAL_TMP_PATH variable.
+  // @see https://docs.acquia.com/acquia-cloud-platform/manage-apps/files/temporary#section-important-considerations
+  $settings['file_temp_path'] = '/tmp';
+
+  if (!empty($ah_site_group) && getenv('DRUPAL_TMP_PATH_IS_SHARED')) {
+    // @see https://acquia.my.site.com/s/article/360054835954-Bulk-Upload-Not-Working-Correctly
+    $settings['file_temp_path'] = sprintf('/mnt/gfs/%s.%s/tmp', $ah_site_group, $ah_site_env);
+  }
+
+  if (getenv('DRUPAL_TMP_PATH')) {
+    $settings['file_temp_path'] = getenv('DRUPAL_TMP_PATH');
+  }
 }
diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docroot/sites/default/includes/providers/settings.container.php b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docroot/sites/default/includes/providers/settings.container.php
@@ -15,10 +15,10 @@
 $vortex_localdev_url = getenv('VORTEX_LOCALDEV_URL');
 if (!empty($vortex_localdev_url)) {
   // Local development URL.
-  $patterns = str_replace(['.', 'https://', 'http://', ','], [
+  $container_patterns = str_replace(['.', 'https://', 'http://', ','], [
     '\.', '', '', '|',
   ], $vortex_localdev_url);
-  $settings['trusted_host_patterns'][] = '^' . $patterns . '$';
+  $settings['trusted_host_patterns'][] = '^' . $container_patterns . '$';
 
   // URL for internal container access (e.g., via drush, in tests etc.).
   $settings['trusted_host_patterns'][] = '^nginx$';
diff --git a/web/sites/default/includes/providers/settings.acquia.php b/web/sites/default/includes/providers/settings.acquia.php
@@ -15,22 +15,23 @@
 declare(strict_types=1);
 
 if (!empty(getenv('AH_SITE_ENVIRONMENT'))) {
+  $ah_site_group = getenv('AH_SITE_GROUP');
+  $ah_site_env = getenv('AH_SITE_ENVIRONMENT');
+
   // Delay the initial database connection.
   $config['acquia_hosting_settings_autoconnect'] = FALSE;
 
   // Include Acquia environment settings.
-  // The path is built dynamically from the AH_SITE_GROUP environment variable
-  // provided by Acquia Cloud.
-  $ah_site_group = getenv('AH_SITE_GROUP');
-  // @codeCoverageIgnoreStart
   if (!empty($ah_site_group)) {
-    $ah_settings_file = sprintf('/var/www/site-php/%s/%s-settings.inc', $ah_site_group, $ah_site_group);
+    $ah_settings_file = getenv('DRUPAL_ACQUIA_SETTINGS_FILE') ?: sprintf('/var/www/site-php/%s/%s-settings.inc', $ah_site_group, $ah_site_group);
+    // @codeCoverageIgnoreStart
     if (!file_exists($ah_settings_file)) {
       throw new \RuntimeException(sprintf('Acquia settings file "%s" not found. Check Acquia Cloud environment configuration.', $ah_settings_file));
     }
     require $ah_settings_file;
+    // @codeCoverageIgnoreEnd
   }
-  // @codeCoverageIgnoreEnd
+
   // Default all environments to 'dev', including ODE environments.
   $settings['environment'] = ENVIRONMENT_DEV;
 
@@ -51,14 +52,28 @@
   // Override the config sync directory with the DRUPAL_CONFIG_PATH environment
   // variable if provided, or fall back to the config_vcs_directory setting
   // provided by Acquia.
-  $drupal_config_path = getenv('DRUPAL_CONFIG_PATH');
-  if (!empty($drupal_config_path)) {
-    $settings['config_sync_directory'] = $drupal_config_path;
+  $config_path = getenv('DRUPAL_CONFIG_PATH');
+  if (!empty($config_path)) {
+    $settings['config_sync_directory'] = $config_path;
   }
   elseif (!empty($settings['config_vcs_directory'])) {
     $settings['config_sync_directory'] = $settings['config_vcs_directory'];
   }
 
   // Automatically create an Apache HTTP .htaccess file in writable directories.
   $settings['auto_create_htaccess'] = TRUE;
+
+  // Allow to override temporary path using per-head mounted directory or
+  // DRUPAL_TMP_PATH variable.
+  // @see https://docs.acquia.com/acquia-cloud-platform/manage-apps/files/temporary#section-important-considerations
+  $settings['file_temp_path'] = '/tmp';
+
+  if (!empty($ah_site_group) && getenv('DRUPAL_TMP_PATH_IS_SHARED')) {
+    // @see https://acquia.my.site.com/s/article/360054835954-Bulk-Upload-Not-Working-Correctly
+    $settings['file_temp_path'] = sprintf('/mnt/gfs/%s.%s/tmp', $ah_site_group, $ah_site_env);
+  }
+
+  if (getenv('DRUPAL_TMP_PATH')) {
+    $settings['file_temp_path'] = getenv('DRUPAL_TMP_PATH');
+  }
 }
diff --git a/web/sites/default/includes/providers/settings.container.php b/web/sites/default/includes/providers/settings.container.php
@@ -15,10 +15,10 @@
 $vortex_localdev_url = getenv('VORTEX_LOCALDEV_URL');
 if (!empty($vortex_localdev_url)) {
   // Local development URL.
-  $patterns = str_replace(['.', 'https://', 'http://', ','], [
+  $container_patterns = str_replace(['.', 'https://', 'http://', ','], [
     '\.', '', '', '|',
   ], $vortex_localdev_url);
-  $settings['trusted_host_patterns'][] = '^' . $patterns . '$';
+  $settings['trusted_host_patterns'][] = '^' . $container_patterns . '$';
 
   // URL for internal container access (e.g., via drush, in tests etc.).
   $settings['trusted_host_patterns'][] = '^nginx$';
