Learn about configuration management and the end-to-end deployment workflow that enables success with Site Factory!
Overview
This is the final segment of a three-part guide covering on how to create a Drupal 10 codebase for Acquia Cloud Site Factory (ACSF). With this end-to-end approach, you can quickly install new Drupal sites or update existing sites so they will inherit the managed configuration in your codebase. We will be working with Acquia's Cloud IDE to simplify the development and deployment process.
Implementing Configuration Management and Proving out the Site Factory Deployment Workflow
I hope this last phase will help you gain a deeper understanding of the process and feel more confident in your ability to successfully deploy your code changes to ACSF.
Making changes to your Codebase: Config Ignore minimal configuration
In order to have configuration differences between your ACSF sites, you will need to list inside the Config Ignore module the configuration files that you wish to be different between your sites.
For example, If you want to have different site names and different blocks added to the Block Layout admin page of each site, you should add the following configurations names to your Config Ignore module:
system.site
block.block.* (will ignore all config entities that starts with block.block)
In your Cloud IDE site, go to the Config Ignore admin page ( /admin/config/development/configuration/ignore) and add the following:
After you make changes to your codebase, it’s a good idea to check for Database updates:
Signorelli IDE:~/project (main) $ drush updb
[success] No pending updates.
Export the new Drupal configuration:
drush cex
Signorelli IDE:~/project (main) $ drush cex
[notice] Differences of the active config to the export directory:
+------------+------------------------+-----------+
| Collection | Config | Operation |
+------------+------------------------+-----------+
| | config_ignore.settings | Update |
+------------+------------------------+-----------+
The .yml files in your export directory (/home/ide/project/config/default) will be deleted and replaced with the active config. (yes/no) [yes]:
> yes
[success] Configuration successfully exported to /home/ide/project/config/default.
/home/ide/project/config/default
Signorelli IDE:~/project (main *) $
Deploy your codebase changes to ACSF
First, you need to push your new codebase changes to your repository:
Signorelli IDE:~/project (main) $ blt artifact:deploy
Would you like to create a tag? (y/n) y
Enter a valid commit message [BLT-003: Config Ignore minimal configuration.]
Enter the tag name for the deployment artifact, e.g., 1.0.0-build 1.0.1-d10acsf
Go to the ACSF Console UI of one of your lower environments and navigate to Administration -> Update code:
In the Site Update page, use the dropdown to select your new codebase (1.0.1-d10acsf):
Click the Update button and wait until the update process finishes:
Check for configuration differences: Create your second ACSF site
It’s recommended that you always create a new site to test that your codebase is working fine, and that it doesn’t create configuration differences.
Create a new ACSF site using your new codebase. Go to Sites and select your group:
Click the “Create a new Site” button:
Give a name to your new site (Example: site2), and click the “Create Site” button:
Create a new Drush alias for your new ACSF site
Go back to your Cloud IDE and create a new Drush alias for your new ACSF site using the aliases.sh bash script. Execute the aliasgenerator.sh bash script and follow the instructions:
./aliasgenerator.sh
Signorelli IDE:~/project (main) $ ./aliasgenerator.sh
| Drush Alias Generator |
|---------------------|
| Main Menu |
|---------------------|
| 1 - New Drush Alias |
| 2 - Exit |
|---------------------|
Select a number from the Main Menu: 1
Selected: New Drush Alias
-------------------------
Make sure to enter the name of a site you already created in your ACSF account.
Example: If the ACSF URL assigned to your new site is site1.acquiatam2.acsitefactory.com
Enter site1
Provide the name of the site you want to create a Drush alias: site2
Is this site name correct?: "site2" (Yes/No/Cancel = y/n/c)
y
Generating the drush alias for site2..
Ready! Going back to the Main Menu...
|---------------------|
| Main Menu |
|---------------------|
| 1 - New Drush Alias |
| 2 - Exit |
|---------------------|
Select a number from the Main Menu: 2
Selected: Exit
--------------
Exiting this script...
Check that your new site doesn’t have configuration differences:
drush @site2.01test cex
Signorelli IDE:~/project (main) $ drush @site2.01test cex
[notice] The active configuration is identical to the configuration in the export directory (../config/default).
../config/default
Connection to acquiatam201test.ssh.enterprise-g1.acquia-sites.com closed.
Signorelli IDE:~/project (main) $
Testing your new codebase: Change the site name of your second site
Login to your new ACSF site using drush uli:
drush @site2.01test uli
Go to the “Basic site settings” admin page (/admin/config/system/site-information) and change the name of your new site:
Save your changes.
Check that this new change in your second site didn’t create a configuration difference:
drush @site2.01test cex
Signorelli IDE:~/project (main) $ drush @site2.01test cex
[notice] The active configuration is identical to the configuration in the export directory (../config/default).
../config/default
Connection to acquiatam201test.ssh.enterprise-g1.acquia-sites.com closed.
Signorelli IDE:~/project (main) $
Making changes to your Codebase: Install a new module
I will install the Shield module to demonstrate the process of adding a new module to your codebase.
Install the new module with Composer
Go to your Cloud IDE instance and execute the following composer command to install the Shield module:
composer require 'drupal/shield:^1.7'
Enable the Shield module:
drush en shield
Go to the Shield module configuration page to make sure the module was installed and enabled successfully (/admin/config/system/shield):
Add the Shield module to the Config Ignore module
If you wish to have the ability to use different Shield credentials per site, you will need to add the Shield configuration file to the Config Ignore module.
Open a new Terminal window in your Cloud IDE instance and execute “drush cex” to find out the filename of the Shield configuration file. Respond NO to the prompt as we don’t want to export the configuration changes at this moment:
drush cex
Signorelli IDE:~/project (main) $ drush cex
[notice] Differences of the active config to the export directory:
+------------+-----------------+-----------+
| Collection | Config | Operation |
+------------+-----------------+-----------+
| | shield.settings | Create |
| | core.extension | Update |
+------------+-----------------+-----------+
The .yml files in your export directory (/home/ide/project/config/default) will be deleted and replaced with the active config. (yes/no) [yes]:
> no
In ConfigExportCommands.php line 155:
Cancelled.
Signorelli IDE:~/project (main) $
Pushing your changes to prod
After you have tested your new codebase changes in your lower environments (test or dev) and created a new test site to make sure your codebase doesn’t generate any configuration differences, you should be ready to update the code in your prod environment.
The prod environment is where you have all your live sites, that’s why it’s so important to test your new codebase changes thoroughly before you push a new codebase to your prod environment.
Login to the ACSF Console UI of your prod environment and go to Administration -> Update code:
In the Site Update page, use the dropdown to select your new codebase (1.0.2-d10acsf):
Click the Update button and wait until the update process finishes:
Check the changes in your existing ACSF sites
Restart your Cloud IDE workspace using your repository
In this last section, I will explain how to restart your Cloud IDE development workspace using your repository with all your latest codebase changes.
Reset your workspace
Go to your Cloud IDE instance, open the Get Started page (Help -> Get Started), and click the “Reset workspace” button:
You can also execute the following command to restart your Cloud IDE workspace:
/ide/reset-workspace.py
Respond “y” to the prompt to execute the reset-workspace.py script:
Signorelli IDE:~/project (main) $ /ide/reset-workspace.py
This will reset the '/home/ide/project' workspace and 'drupal' database without an option to recover.
Do you want to continue? [y/n] y
✓ The 'drupal' database is reset.
✓ The '/home/ide/project' workspace is reset.
Signorelli IDE:~/project $
Clone your repository
Congratulations on successfully completing this three-step guide! First, we navigated through the process of creating a new Drupal 10 codebase that is configured for ACSF. Then, we created a custom Drupal installation profile. And in this last phase, we went through a detailed explanation of configuration management and deployment workflow on Site Factory. I sincerely hope you found this guide helpful.
Go to the Config Ignore admin page of your Cloud IDE site and add “shield.settings” to the end of the list (/admin/config/development/configuration/ignore):
Export your new Drupal configuration
After installing a new module, it’s always recommended to see if there are pending database changes:
Run the following BLT command each time there is a core update or if a new module was installed:
blt recipes:acsf:init:drush
Export the new Drupal configuration:
drush cex
Signorelli IDE:~/project (main *) $ drush cex
[notice] Differences of the active config to the export directory:
+------------+-------------------------+-----------+
| Collection | Config | Operation |
+------------+-------------------------+-----------+
| | core.extension | Update |
| | config_ignore.settings | Update |
+------------+-------------------------+-----------+
The .yml files in your export directory (/home/ide/project/config/default) will be deleted and replaced with the active config. (yes/no) [yes]:
> yes
[success] Configuration successfully exported to /home/ide/project/config/default.
/home/ide/project/config/default
Signorelli IDE:~/project (main *) $
Add your new module to your profile’s .info.yml file
Every time you add a new module to your codebase, you will need to add it to your profile’s .info.yml file. Open your profile’s .info.yml file (/home/ide/project/docroot/profiles/custom/tamprofile/acsfprofile.info.yml) and under the “install” section, add the new installed module (shield):
First, you need to push your new codebase changes to your repository:
git add -A
git commit -m "BLT-004: Added the Shield module."
git push
Deploy your codebase to ACSF:
blt artifact:deploy
I named this new deployed code: 1.0.2-d10acsf
Signorelli IDE:~/project (main) $ blt artifact:deploy
Would you like to create a tag? (y/n) y
Enter a valid commit message [BLT-004: Added the Shield module.]
Enter the tag name for the deployment artifact, e.g., 1.0.0-build 1.0.2-d10acsf
Go to the ACSF Console UI of one of your lower environments and go to Administration -> Update code:
In the Site Update page, use the dropdown to select your new codebase (1.0.2-d10acsf):
Click the Update button and wait until the update process finishes:
Check the changes in your existing ACSF sites
After you pushed your new codebase to the test environment and updated all the existing sites in there, you should always check that the changes were applied successfully to your sites.
Go to the Config Ignore module admin page of one of your ACSF sites to check if it has the new “shield.settings” on the list:
Enable the Shield module and check for Configuration Differences
Let’s activate and configure the Shield module on one of your ACSF sites. Go to the Shield module admin page ( /admin/config/system/shield), check the “Enable Shield” checkbox and assign a user and password under the Credentials section. Click the “Save configuration” button to save the changes:
You should get the Shield “Sign In” prompt right after you hit the “Save configuration” button:
Enter your Shield credentials to test everything is working fine.
Check for configuration differences
Now that one of your sites has the Shield module activated, you should check if there are any configuration differences. Go to your Cloud IDE terminal and execute “drush cex” against your ACSF site that has the Shield module activated:
Signorelli IDE:~/project (main) $ drush @site2.01test cex
[notice] The active configuration is identical to the configuration in the export directory (../config/default).
../config/default
Connection to acquiatam201test.ssh.enterprise-g1.acquia-sites.com closed.
Signorelli IDE:~/project (main) $
We don’t have any configuration differences. That means we configured the Config Ignore module correctly to ignore any configuration changes of the Shield module across your ACSF sites.
Create a new ACSF site to test your new codebase
It’s recommended that you always create a new site to test that your codebase is working fine and that it doesn’t create configuration differences.
Create a new ACSF site using your new codebase. Go to Sites and select your group:
Click the “Create a new Site” button. Give a name to your new site (Example: site3), and click the “Create Site” button:
Create a new Drush alias for your new ACSF site
Go back to your Cloud IDE and create a new Drush alias for your new ACSF site using the aliasgenerator.sh bash script. Execute the aliasgenerator.sh bash script and follow the instructions:
./aliasgenerator.sh
Signorelli IDE:~/project (main) $ ./aliasgenerator.sh
| Drush Alias Generator |
|---------------------|
| Main Menu |
|---------------------|
| 1 - New Drush Alias |
| 2 - Exit |
|---------------------|
Select a number from the Main Menu: 1
Selected: New Drush Alias
-------------------------
Make sure to enter the name of a site you already created in your ACSF account.
Example: If the ACSF URL assigned to your new site is site1.acquiatam2.acsitefactory.com
Enter site1
Provide the name of the site you want to create a Drush alias: site2
Is this site name correct?: "site3" (Yes/No/Cancel = y/n/c)
y
Generating the drush alias for site3..
Ready! Going back to the Main Menu...
|---------------------|
| Main Menu |
|---------------------|
| 1 - New Drush Alias |
| 2 - Exit |
|---------------------|
Select a number from the Main Menu: 2
Selected: Exit
--------------
Exiting this script...
Check that your new site doesn’t have configuration differences:
drush @site3.01test cex
Signorelli IDE:~/project (main) $ drush @site3.01test cex
[notice] The active configuration is identical to the configuration in the export directory (../config/default).
../config/default
Connection to acquiatam201test.ssh.enterprise-g1.acquia-sites.com closed.
Signorelli IDE:~/project (main) $
If you see the above message stating that there are no configuration changes in your newly installed ACSF site, that means you configured your codebase correctly.
After you pushed your new codebase to the test environment and updated all the existing sites in there, you should always check that the changes were applied successfully to your sites.
In your Cloud IDE, open a new terminal window and make sure you are inside the project folder:
cd ~/project
Clone your repository down using the following git command syntax:
git clone YourRemoteRepositoryURL .
Make sure to add the final period “.” so you clone your repository inside the project folder. Example:
Now you should be able to install a new site using the existing configuration on disk:
blt setup --no-interaction
You should have no configuration differences between the new site’s database and the existing configuration on disk:
drush config:status
Signorelli IDE:~/project (main *) $ drush config:status
[notice] No differences between DB and sync directory.
Try to access your new Cloud IDE with “drush uli”:
drush uli
If you get the following error message, it’s probably because you are missing the .htaccess file from the docroot folder:
Look inside your docroot folder:
Signorelli IDE:~/project/docroot (main) $ ls -lA
total 72
-rw-r--r-- 1 ide ide 315 Apr 6 13:21 autoload.php
drwxr-xr-x 12 ide ide 4096 Mar 24 16:45 core
-rw-r--r-- 1 ide ide 1025 Apr 6 09:44 .csslintrc
-rw-r--r-- 1 ide ide 151 Apr 6 09:44 .eslintignore
-rw-r--r-- 1 ide ide 41 Apr 6 09:44 .eslintrc.json
-rw-r--r-- 1 ide ide 1495 Apr 6 09:44 example.gitignore
-rw-r--r-- 1 ide ide 173 Apr 6 09:32 .gitignore
-rw-r--r-- 1 ide ide 2471 Apr 6 09:44 .ht.router.php
-rw-r--r-- 1 ide ide 549 Apr 6 09:44 index.php
-rw-r--r-- 1 ide ide 94 Apr 6 09:44 INSTALL.txt
drwxr-xr-x 4 ide ide 4096 Apr 6 09:44 modules
drwxr-xr-x 4 ide ide 4096 Apr 6 09:44 profiles
-rw-r--r-- 1 ide ide 3205 Apr 6 09:44 README.md
-rw-r--r-- 1 ide ide 1706 Apr 6 09:44 robots.txt
drwxr-xr-x 5 ide ide 4096 Apr 6 09:44 sites
drwxr-xr-x 3 ide ide 4096 Apr 6 09:44 themes
-rw-r--r-- 1 ide ide 804 Apr 6 09:44 update.php
-rw-r--r-- 1 ide ide 4039 Apr 6 09:44 web.config
Signorelli IDE:~/project/docroot (main) $
Open the .gitignore file located inside the docroot folder, you should see that the .htaccess file is listed to be ignored:
Remove the docroot/.gitignore file:
rm /home/ide/project/docroot/.gitignore
Copy the htaccess file that’s located inside the project/docroot/core/assets/scaffold/files/ folder to the docroot folder as .htaccess:
Go back to the project folder and clear Drupal’s cache:
cd ~/project
drush cr
Try to access your new Cloud IDE with “drush uli”:
drush uli
With the new .htaccess file you should be able to access the site without errors:
Copy a site from ACSF to Cloud IDE with BLT
Edit your blt/blt.yml file and modify the value of the drush -> aliases -> remote key with the ACSF website that you wish to copy down to your Cloud IDE, for this tutorial, I will use the site2.01test site:
“site2” is the alias of an existing site and “.01test” is the environment where that site lives.
Signorelli IDE:~/project (main *) $ drush rsync @site2.01test:%files docroot/sites/default/files
Copy new and override existing files at docroot/sites/default/files. The source is acquiatam2.01test@acquiatam201test.ssh.enterprise-g1.acquia-sites.com:/var/www/html/acquiatam2.01test/docroot/sites/g/files/utfjsx5000431test/files/? (yes/no) [yes]:
> yes
Signorelli IDE:~/project (main *) $
Clear the cache of your new cloned site:
drush cr
Open your local Cloud IDE website to see your new cloned site. On the Menu, navigate to “Manage Drupal Application” -> “Open Drupal Application”:
Because we cloned the “site2” site, we should see the Shield module username and password prompt as we previously activated and configured the Shield module on the “site2” ACSF site:
In my case, my shield credentials for site2 is admin and pass123:
Access your new cloned site with “drush uli”:
drush uli
Make sure everything looks fine. It’s always a good idea to check for configuration differences:
Signorelli IDE:~/project (main *) $ drush cex
[notice] The active configuration is identical to the configuration in the export directory (/home/ide/project/config/default).
/home/ide/project/config/default
Signorelli IDE:~/project (main *) $ drush config:status
[notice] No differences between DB and sync directory.
Signorelli IDE:~/project (main *) $
Push your new codebase changes to your repository which includes the new .htaccess file in your docroot folder. The next time you restart your Cloud IDE workspace using your repository it shouldn't fail due to the missing .htaccess file.
First, execute the following BLT command to download and extract the updated Acquia Cloud Site Factory Connector:
Site Factory