5 Best Practices for Deploying Acquia Site Studio Drupal Sites
Acquia Site Studio has many configurable features in its administration section—from Components to Templates, custom style settings, branding options, iconography, and more. You can do a great deal from the admin user interface but deploying changes to production sites can be quite challenging, particularly if you’re a site builder.
In this post we’ll review some best practices for deploying updates that we’ve learned from the Drupal sites we’ve built and launched with Acquia Site Studio. These best practices are geared toward helping ambitious site builders, a group that Dries Buytaert said that Drupal wants to focus on at this year’s Drupalcon.
Use the Config Ignore Module
Before installing Acquia Site Studio, make sure you have downloaded and enabled the Config Ignore module first.
The Config Ignore module lets you list names of configuration sets to ignore. This means that it won’t export or import configuration that matches anything you set. This is useful when you don’t want to have configuration overridden or imported. Acquia Site Studio has its own packaging system to track configuration that we highly recommend using.
In the Config Ignore settings in the Drupal admin, set these patterns:
cohesion_custom_styles.*
cohesion_templates.*
cohesion_elements.*
cohesion_base_styles.*
cohesion_website_settings.*
cohesion_style_guide.*
cohesion_style_helpers.*
cohesion_theme.* The only file tracked by normal Drupal configuration is cohesion.settings which holds basic information and your Acquia Site Studio license key. You can also add it if you want, but you must re-enter the license key on each site (dev, staging, and production). The objective is to ensure Drupal is unaware of Acquia Site Studio.
The reason these files are ignored is because they’re exported and tracked in the package(s) Acquia Site Studio creates. Having Acquia Site Studio configuration files mixed into the normal Drupal configuration can present import errors on deployments that are difficult to resolve. Instead, export the Acquia Site Studio settings as a full package or into individual package(s) you can deploy to staging or production environments.
Do Not Export “Everything” into a Single Package
In the administrative area of Site Studio or using Drush on the command line you can export all the configuration related to Acquia Site Studio into a package. For the “Full” package (i.e., everything) you can select what to include in the export.
You want all of these, except for three of them. It’s wise to uncheck Packages, Image styles, and Views. For most Drupal projects you’ll make extensive use of Image styles and Views to construct parts of your website, whether it’s used within Acquia Site Studio components or not. Image styles and Views should be tracked by the normal Drupal configuration system.
This way, Image styles and Views are independent from Acquia Site Studio. Making changes to them will be easier to export and deploy as normal Drupal configuration rather than using Acquia Site Studio to generate a new package and deploy. The package export should only contain items relevant to Acquia Site Studio.
Ensure the Image Browser for Configuration is Correct
This setting is one of the most important to get right for smooth deployments with Acquia Site Studio.
When setting up Acquia Site Studio, you have an option of setting the image browser to use within Components:
Make sure that the image browser for config is either set to no image browser or a file-based browser like IMCE.
If this is not set, you can’t successfully export component or template definitions that contain images, icons, or other static assets. If you select browsers that use Media entities for this, all your exports will contain ID references to media entities that won’t exist on other environments, and your deployments will be missing these files. Even if you add these to staging or production, future deployments will reset those values. You may even get several errors when trying to import packages on higher environments if this is not set properly.
By setting the image browser for config correctly, it ensures that the image data is included within the exported files Acquia Site Studio produces. Otherwise, even though deployments will appear to be successful those images won’t be present, and this can be hard to track down.
Avoid Using Blocks within Components or Templates
If you can, try to avoid placing and using Block entities within Acquia Site Studio Component or Template definitions.
Blocks are content entities in Drupal and won’t be exported (just like Media entities mentioned above). What happens is that you can deploy your changes to staging or production only to find that blocks you used won’t be present.
This requires you to go back through on these sites, create those blocks, place them in the Acquia Site Studio hidden region of the theme, configure them, and put them back into those components. If you use a lot of Blocks to define components or templates in Acquia Site Studio, this makes for painful deployments since it creates a lot of manual work. It lengthens your site downtime during deployments because you need time to get them all back in place, and it makes it hard for you to track what is and isn’t missing.
One important distinction is that it is okay to have Components that let an editor select from a list of blocks when creating actual content—it’s only the Component or Template definitions that should avoid relying on them.
Maintain Communication with Your Team
Lastly, if you’re collaborating with several people on an Acquia Site Studio project—coordinate and communicate. It is easy to overlap and overwrite someone's work within Site Studio’s interface. Talk with your team to ensure people know exactly what you’re working on and vice versa. If multiple people try to edit a template, component, or style definition at the same time, none of the changes will be saved. You can avoid this by specifically calling out what you’re working on and letting others know when you have finished in an area so someone else can complete their task.
At the end of a sprint, you can then package up the work and deploy it to your staging or production environments.
Get More Out of Your Acquia Site Studio Site
Need help wrangling issues in Acquia Site Studio? We have several Acquia Site Studio certified staff ready to assist you. We can help resolve styling issues, build new components, or integrate search and third-party services to Site Studio components and templates. Reach out to find out more about how we can help you make the most of Acquia Site Studio.