Site Studio
Global settings and config options
Site Studio exposes a set of low-level settings and configuration overrides that you add directly to your site's settings.php file. These options control debugging visibility, API connectivity, file system behavior, and batch processing limits. Because they are defined in PHP rather than stored in the database, they are environment-aware by nature — you can apply different values per environment (development, staging, production) by placing them in the appropriate environment-specific include file. None of these settings are required for a basic installation, but several are essential for production hardening, CI/CD pipeline configuration, and performance tuning on larger sites.
Site Studio$settings entries — PHP runtime values evaluated on each request. They are not exported as Drupal configuration and are environment-specific by design. Use them to control behaviour that should differ between local, staging, and production environments.$config entries — These override Drupal configuration objects stored in the database. While they are technically part of the config system, they should be protected from being overwritten by config imports using a module such as config_ignore.$settings['sync_max_entity']This setting controls the maximum number of Site Studio entities processed per batch iteration during a sync package import operation. When Site Studio imports a sync package, it processes entities in batches to avoid exhausting PHP memory and execution time limits. This setting defines the batch chunk size.
The default value is 10. A lower value reduces memory pressure per batch request at the cost of more total batch iterations (and a longer overall import). A higher value processes more entities per iteration, which is faster but consumes more memory.
When to use it: Adjust this setting when you encounter PHP memory exhaustion errors or HTTP timeout errors during large sync package imports. Lowering the value (for example, to 5 or even 1 on memory-constrained environments) can resolve Allowed memory size exhausted or Maximum execution time exceeded errors. Conversely, if your hosting environment has generous PHP memory limits and you want to speed up imports on large packages, you can increase this value cautiously.
Caveats: Setting this value too high on environments with low PHP memory limits will cause import failures. The optimal value depends on your environment's memory_limit and max_execution_time PHP settings, as well as the complexity of the entities being imported. Test changes in a development environment before modifying in production. This setting affects only the sync import batch — it does not affect the rebuild batch (see rebuild_max_entity below).
Placement: Add to settings.php. Can be set per-environment if different environments have different resource profiles.
// Process 25 entities per sync import batch on environments with ample memory.
$settings['sync_max_entity'] = 25;$settings['rebuild_max_entity']This setting controls the maximum number of Site Studio entities processed per batch iteration during a full or partial rebuild operation. Site Studio rebuilds regenerate all compiled CSS, template files, and style outputs from the stored configuration. Because rebuild operations are among the most resource-intensive tasks Site Studio performs, this batch size directly affects memory consumption and execution time per request.
The default value is 10. Lower values reduce peak memory usage per batch step; higher values reduce the total number of steps and can speed up the overall rebuild on well-resourced environments.
When to use it: Reduce this value when encountering Allowed memory size exhausted PHP fatal errors, white screens, or timeouts during rebuilds on sites with many components, custom styles, or templates. This is a common tuning requirement on large or complex Site Studio installations. Reducing to 5 or lower can make rebuilds more stable on hosting environments with tighter PHP memory limits. Increasing this value can accelerate rebuilds in automated deployment pipelines where PHP memory limits are set high.
Caveats: This setting affects all rebuild operations — both full rebuilds triggered manually via the admin UI or Drush (sitestudio:rebuild), and partial rebuilds triggered automatically by package imports. Always validate changes to this setting in a staging environment that mirrors your production PHP configuration. Note that rebuilds also consume API quota — extremely small batch sizes on very large sites may approach rate limits.
Placement: Add to settings.php. Consider setting a lower value on production if your environment has constrained PHP memory, and a higher value on CI/CD or build environments with elevated resource limits.
// Process 25 entities per rebuild batch — adjust based on available PHP memory.
$settings['rebuild_max_entity'] = 25;$settings['dx8_json_fields']When set to TRUE, this setting exposes raw JSON fields within the Site Studio administrative interface. These fields show the underlying JSON data structures that Site Studio uses to store component, template, and style configuration — data that is normally hidden behind the visual editor UI.
When to use it: Use this setting when debugging unexpected behavior in components or styles, when building custom integrations that need to inspect or manipulate raw configuration data, or when working with Acquia Support to diagnose a specific issue.
Caveats: This setting is intended strictly for development and debugging environments. Exposing raw JSON fields in a production environment is unnecessary and may confuse content editors. Disable this setting (or omit it entirely, as FALSE is the default) before go-live.
Placement: Add to settings.php, or preferably to an environment-specific include (for example, settings.local.php or a development environment override file) to ensure it is never accidentally enabled in production.
// Enable JSON debug fields — development environments only.
$settings['dx8_json_fields'] = TRUE;$settings['dx8_editable_api_url']When set to TRUE, this setting unlocks the API server URL field on the Site Studio Account Settings page (/admin/cohesion/configuration/account-settings), making it editable in the UI. By default, this field is read-only and pre-populated by Site Studio.
When to use it: Use this setting in development or staging environments where you need to point Site Studio at a non-standard or internal API endpoint — for example, when testing against a staging version of the Site Studio API, working behind a proxy, or troubleshooting API connectivity issues with Acquia Support guidance.
Caveats: Changing the API URL to an incorrect or unreachable endpoint will prevent Site Studio from functioning entirely, including asset imports and rebuilds. Do not enable this setting in production unless explicitly directed by Acquia Support.
Placement: Add to settings.php. Restrict to non-production environments using environment-specific includes wherever possible.
$settings['dx8_editable_version_number']When set to TRUE, this setting exposes a version number field on the Site Studio Account Settings page. This field allows the version number reported to the Site Studio API to be manually overridden.
When to use it: This is a development-only utility, typically used when testing version-specific API behavior, working with pre-release builds, or reproducing version-dependent issues in a controlled environment. It is not intended for routine use.
Caveats: Manually overriding the version number can cause the API to respond with incorrect assets or incompatible data, which may break component rendering and style generation. This setting should never be enabled in production. It does not affect the installed version of the Site Studio module — it only affects what version number is communicated to the API.
Placement: Add to settings.php, restricted to development environments only.
// Expose the API version number field — Acquia support use only.
$settings['dx8_editable_version_number'] = TRUE;$settings['dx8_no_api_keys']When set to TRUE, this setting hides the API key and Agency key fields from the Site Studio Account Settings page in the Drupal UI. The fields are suppressed entirely and will not appear to administrators browsing the settings page.
When to use it: Use this setting when API credentials are managed programmatically via $config['cohesion.settings'] overrides in settings.php (see Global config options below) or via environment variables. In automated deployment pipelines, CI/CD environments, or multi-environment setups where credentials are injected at the infrastructure level, hiding the UI fields prevents accidental manual overrides that could break the configured credential chain.
Caveats: If you enable this setting but do not supply valid credentials via $config['cohesion.settings']['api_key'] and $config['cohesion.settings']['organization_key'] elsewhere in settings.php, Site Studio will be unable to authenticate and all rebuilds and asset imports will fail. This setting does not itself provide or inject credentials — it only controls their UI visibility. Ensure credentials are supplied through another mechanism before enabling this in any environment.
Placement: Add to settings.php. Particularly recommended for production and staging environments where credentials are managed via environment variables.
// Hide API key UI fields when credentials are managed via settings.php.
$settings['dx8_no_api_keys'] = TRUE;$settings['dx8_no_google_keys']When set to TRUE, this setting hides the Google Maps API key configuration page (/admin/cohesion/configuration/google-map-api-key) from the Site Studio admin interface.
When to use it: Use this setting when your site does not use the Site Studio Google Map element and you want to prevent editors or administrators from encountering an irrelevant configuration page. It is also appropriate when Google API credentials are managed at the infrastructure or environment variable level rather than through the UI, and you want to suppress the UI entry point to avoid confusion or accidental misconfiguration.
Site Studio uses two separate Google Maps APIs: the Maps JavaScript API (for front-end map rendering) and the Maps Embed API (for map previews in the Site Studio editor UI). If your site uses either, do not suppress this page — configure keys there instead. See Google Maps API key for setup instructions.
Caveats: Hiding this page does not disable or remove any Google Maps functionality. If a Google API key is already stored in the database and this setting is enabled, the existing key will continue to be used. This setting only affects UI access to the configuration page.
Placement: Add to settings.php. Applies to all environments where it is present.
// Hide Google API key configuration page when not using Google integrations.
$settings['dx8_no_google_keys'] = TRUE;$settings['coh_temporary_stream_wrapper']This setting overrides the temporary file stream wrapper that Site Studio uses when processing and generating files — such as compiled CSS, generated assets, and temporary build artifacts — during rebuild operations.
By default, Site Studio uses Drupal's standard temporary:// stream wrapper, which maps to the system's configured temporary directory. This setting allows you to substitute a custom stream wrapper registered by your site or hosting environment.
When to use it: Use this setting when your hosting environment uses a non-standard or custom temporary filesystem — for example, a RAM-backed tmpfs mount for performance, a shared NFS volume in a multi-server setup, or a custom stream wrapper provided by a contributed or custom module. It can also be useful in containerized environments where the default tmp directory has restricted permissions or limited space.
Caveats: The stream wrapper you specify must be registered and functional before Site Studio attempts to use it. Pointing Site Studio at an unregistered or misconfigured stream wrapper will cause rebuild failures and may leave corrupted temporary files. Ensure the target directory has adequate space — large sites with many components can generate significant temporary output during a full rebuild. Test this setting in a development environment before applying it to production.
Placement: Add to settings.php. The value must be a valid, registered Drupal stream wrapper URI scheme including the trailing ://.
// Direct Site Studio temporary build files to a custom stream wrapper.
$settings['coh_temporary_stream_wrapper'] = 'mytemp://';$settings['site_studio_sync']This setting defines the filesystem path that Site Studio's Sync sub-module uses as its sync directory — the location where Site Studio sync packages are read from during automated package imports (for example, via Drush commands such as sitestudio:package:import or sitestudio:package:multi-import).
By default, Site Studio uses its own internal default path. This setting allows you to redirect it to a custom location that aligns with your project's repository and deployment structure.
When to use it: Use this setting when you want Site Studio sync packages to live in a specific directory in your codebase — for example, alongside your Drupal configuration export directory (../config/sync) to keep all exportable configuration in one predictable location. This is common in deployment pipelines where packages are committed to version control and then automatically imported during a deployment hook or CI/CD step.
Caveats: The path is relative to the Drupal webroot unless you supply an absolute path. Ensure the directory exists and is readable by the PHP process at the time Site Studio attempts to read from it. If the path is incorrect or inaccessible, sync imports will fail silently or throw filesystem errors. This setting affects only the Sync sub-module import path — it does not affect where packages are exported to via the UI.
Placement: Add to settings.php. The value should be consistent across all environments where automated sync imports are expected to run, or set per-environment in environment-specific includes if paths differ.
// Store Site Studio sync packages outside the document root.
$settings['site_studio_sync'] = '../config/site_studio';$config['cohesion.settings']['api_key']This setting overrides the Site Studio API key stored in Drupal database configuration, supplying it directly via settings.php. The API key authenticates your Drupal site with the Site Studio API service and is required for all Site Studio functionality, including asset imports, rebuilds, and style generation.
When to use it: This override is essential in any environment where Drupal configuration management (config sync) is in use. Without this override — and without proper config_ignore rules protecting cohesion.settings — a configuration synchronization deployment can delete your API key from the database, causing all rebuilds to fail and resulting in potential site downtime. By defining the key in settings.php, it survives config syncs and is not included in version-controlled configuration exports.
The recommended pattern is to inject the value from an environment variable rather than hardcoding it:
$config['cohesion.settings']['api_key'] = getenv('SITE_STUDIO_API_KEY');This keeps credentials out of version control entirely and allows each environment to use its own key.
Caveats: Never commit a real API key to version control. If you hardcode the key in settings.php and that file is committed to a repository, your credentials are exposed. Use environment variables set via your hosting platform (such as Acquia Cloud environment variables) and the getenv() pattern shown above. Ensure config_ignore is also configured to protect cohesion.settings as a defense-in-depth measure. See Configuration management and deployment for the full credential protection workflow.
Placement: Add to settings.php. Must be present on every environment where Site Studio is active. Configure per-environment using environment variables.
// Recommended: inject API key from a server-level environment variable.
$config['cohesion.settings']['api_key'] = getenv('SITE_STUDIO_API_KEY');
// Alternative for local development only (never commit a live key to VCS).
$config['cohesion.settings']['api_key'] = 'your-api-key-here';See also: $settings['dx8_no_api_keys'] to hide the UI fields once credentials are managed via this override.
$config['cohesion.settings']['organization_key']This setting overrides the Site Studio organization key — also referred to as the Agency key in the UI and older documentation — stored in Drupal database configuration. Together with the API key, the organization key forms the two-part credential set required to authenticate your site with the Site Studio API. Contact your Acquia Account Manager to obtain both credentials.
When to use it: As with the API key override above, this setting is required in any environment that uses Drupal configuration management. A configuration synchronization that is not protected by config_ignore will overwrite the cohesion.settings configuration object in the database, wiping both the API key and organization key simultaneously. Defining the organization key in settings.php protects it from being lost in deployments.
The recommended pattern is to inject the value via an environment variable:
Caveats: The same security considerations apply as for the API key — do not hardcode credentials in files tracked by version control. Note that organization_key is the configuration property name used in settings.php; the Drupal UI refers to this field as the Agency key. Both names refer to the same credential. If you define the API key via settings.php but omit the organization key (or vice versa), Site Studio authentication will fail. Always set both overrides together.
Placement: Add to settings.php. Must be present on every environment alongside api_key. Configure per-environment using environment variables.
// Recommended: inject organisation key from a server-level environment variable.
$config['cohesion.settings']['organization_key'] = getenv('SITE_STUDIO_ORG_KEY');Site Studio communicates with the external style compilation API to generate CSS and other frontend assets. The HTTP client used for this communication (CohesionApiClient) applies a fixed 30-second request timeout. There is currently no $settings variable available to override this timeout value.
In practice, this timeout is rarely reached under normal operating conditions. However, it may be triggered on environments with unusually high latency to the https://api.sitestudio.acquia.com endpoint, or during rebuild operations on sites with very large numbers of components and styles.
If you are experiencing rebuild or import failures that appear to stall at the style compilation step, check your server's outbound connectivity to https://api.sitestudio.acquia.com and review your PHP error logs for timeout-related messages. Contact Acquia Support if the issue persists.
If this content did not answer your questions, try searching or contacting our support team for further assistance.
If this content did not answer your questions, try searching or contacting our support team for further assistance.