Guide to Profitable Sales
Drupal CI/CD Workflow
How is it put together?
The Drupal CI/CD: Initial Test of Platform CI with Lando repository is designed to be a convenient starting point for website builders. The repository’s README offers quick instructions on how to use it. However, if you encounter version changes, prefer a operating system other than a Mac, or prefer DDEV or Docksal over Lando, you may need to delve into the underlying details. This is where this companion site hosted on GitHub pages comes in. It provides a comprehensive overview of the repository’s processes, including code modifications, module additions, and more. That starts below with a summary review of the parts but is also supported by step-by-step detail if needed; Go here and keep hitting “next” at the end of each page
1) Prerequisites provides a setup to assure your computer has the base tools to make things work. It assures you have ‘npm’, ‘homebrew’, ‘nodejs’, ‘git’, and an Integrated Development Environment (IDE) called VSCode plus a number of its ‘extensions’ on your own computer. It also includes ‘Composer’ and ‘Docker’; however, if you already have those you may need to backpeddle a little to allow our process to automatically install the appropriate version. Finally, we make sure you have a GitHub account and know how to SSH connect to it; and a Platform.sh account whose ‘CDI’ option you will need to use. We set up the SSH relationship between our local machine and GitHub if it doesn’t already exist. And set SSH up between GitHub and Platform.sh for our project’s build code. Make sure you have Platform API tokens set too. (It is recommended that you use your GitHub account to sign up for Platform.sh because then your SSH connection will be between your local machine, GitHub AND Platform.sh.)
2) Platform.sh is a critical foundation for you. It is going to be the source of a “TEMPLATE” for a Drupal CMS installation. The critical thing is matching the Drupal version for the template to our project version number you clone from GitHub. Platform.sh does a pretty good job of making set up simple and provides good documentation. Our documentation offers three different levels of getting you started:
. The Short-cut assumes you are an old hand working with web stuff.
. The Regular offers basic guidance and a good reminder source.
. The Step by Step is a cookbook with screen shots and detailed guidance.
3) Once up you have Drupal running on Platform.sh you bring a copy local for faster, safer by isolating what you are working on from any “production” environment. Your VScode IDE will pay dividends. You point VSCode at the local copy of your project on your harddrive. In the left panel of VSCode you view the directory structure and make sure you are in your ‘user root directory’. In the terminal area of VSCode type platform on the command line which invokes the Platform.sh “CDI” to install a copy of the hosted project on your local machine. (Remember to be sitting in the directory level 'above' where your new project will be and all the files will be below that). A terminal type menu will present options on the command line and since you remember the ‘name’ of your project just pick it from those listed (if its your first time doing this it won’t be hard because it is the only project you will see listed). Pull it down but don't do anything to it (ESPECIALLY DO NOT CONFIG EXPORT IT). The upper right panel of VSCode provides a line-by-line view of any individual files you highlight in the directory view. If you click the keyboard combination of shift-command-P it opens a command bar usefult for Git and GitHub repository connections. These and other goodies are offered by the extensions recommended as part of this project’s prerequisites.
The explanation of how this CI/CD Workflow Project is ‘built’ has been consistent with what you would do to ‘use it’. It mostly focuses on setting up your computer and work environment. To use the project, you’ll clone it from GitHub and integrate it with the Drupal template you got from Platform.sh. What you get with that clone already has what is shown next; so continuing here is optional. The rest of the page below continues to explain the underlying components of the clone. If you want to customize your workflow or manage tools within different environments (develop, staged, main), understanding that underlying detail may be helpful.
Just Clone & Use
How put together, continued
If your project is already integrated between these platforms, what else is there to consider? While using Platform.sh as a GitOps host is a great start, there are additional steps to set up a robust CI/CD Workflow. This includes tweaking development configuration with specialized tools, such as automatic environment indicator names and color bars to prevent confusion. It also involves establishing limited but visually informative connections to database stored content, which can enhance development performance while providing real-world context. These components are crucial for a successful workflow.
4) For our CI/CD Workflow, we make sure that our .gitignore file recommendations are tailored to meet its unique needs. By putting your project under ‘Git’ control, you gain numerous benefits. But before you jump into the 'init' command, make sure you have our .gitignore file. With Drupal using Composer, version control coordination via our composer.json file serves as a handy recipe for everything your project requires. This prevents unnecessary transfer of thousands of files between your local machine, GitHub repository, and Platform.sh host environment. Our .gitignore file avoids transfering files the recipe covers and also excludes log files, IDE or sass generated intermediary files, and more. Once the .gitignore file is in place on your local Drupal copy, the CI/CD Workflow Project is ready to be placed into your GitHub repository. Now, feel free to run ‘git init’ and enjoy the benefits.
5) Congratulations on getting your basic Platform.sh Drupal template up and running on your host and local machine! Now it’s time to make your local copy, with your .gitignore edits, truly “YOUR” Project in your GitHub repository. If you’re using the recommended VSCode, simply press shift-command-P to bring up the command pallet and type Publish to GitHub. With the extensions we added and your SSH connection, you’ll be prompted to sign in to GitHub. Then, start typing the name of your project in the command pallet and select either the public or private option to publish to your GitHub account; noting the name of your GitHub account followed by the project name. Now, your project is integrated between GitHub, Platform.sh, and your local machine Lando container.
6) Correct .lando.yml tooling is essential to make sure Drush will work properly. Drush is a command line tool that allows a bunch of Drupal actions to be taken with a short-cut. People who do a lot of work in Drupal find it essential. Even if you just use it to do a drush cr to clear the cache as you work, you will find it quickly become a real time saver for certain things. For some reason, the Platform.sh template you pull for Drupal with Lando contains drush automatically but the .lando.yml file that is included has the tooling within its configuration set to service: app and you need to edit that to say service: drupal.
7) The Mid-Point Update in the detailed documentation outlines of the logic behind using a ‘develop’, ‘staged’, and ‘main’ (production) environment approach to achieve the CI/CD Workflow. Notes is how we can use standard ‘Git’ commands to manage version control, rollbacks, testing, and production release. These Git commands can be run from your VSCode IDE or directly from its terminal command line. Also described is how ‘Drupal configuration’ is managed between these different environments; putting certain Drupal modules only in certain environments.
8) DON'T SPLIT IT YET! We are heading toward those additional named environments beyond ‘main’. Before going there, first we want to bring “YOUR” project up-to-date. So you have the basic CI/CD Project Drupal site in place by cloning it and then doing the integration between the local machine, GitHub, and the Platform.sh host. You can open your Drupal project and you will most likely find it warning you that an update exists. If you don’t know Drupal yet, this warning exists lots of times and it is NOT mandatory that you do updates. However, with a new project it makes sense for the cleanest starting point. Using our VSCode IDE we will ‘stage the changes’ (clicking the plus sign), click the blue bar with checkmark that says ‘commit’, and if all is going as we want we can click the blue bar that now says ‘sync changes’. You may get a confirming message indicating this will ‘pull and push commits from and to origin/main’; that message option can be turned off so if you have done that in prior use of your VSCode IDE you may just run. The key thing here is that the ‘orgin/main’ is telling you the branch environment project branch and recall we named our starting point environment branch ‘main’ when first establishing the project on Platform.sh. Sometimes people who have worked with Git/GitHub in the past called it ‘master’. But not only is ‘main’ the modern standard, it is also is key you use ‘main’ for the CI/CD Project to work correctly. You may as well run a Platform.sh backup on you host at this point too.
*********
make sure you have the write and timeout settings in place doing the Drupal core update
9) It made sense to push “YOUR” fresh project code and to back up Platform.sh because local, GitHub, and Platform.sh are all talking to each other by your signing up for Platform.sh with our GitHub account and establishing SSH and Token connections so all the environments talk to each other. The detailed documentation moves to showing the typical directory structure of a Drupal project. While this is benefical generally so you better understand how Drupal works, it is also an introduction into the where and how of Drupal modules. Drupal core comes with a bunch of standard modules and you got those from the Plaform.sh template Lando Drupal installation. Where the real strength of Drupal comes from is the huge number of additional capabilities that can be achieved by adding on other modules. This includes some key module additions that are part of the CI/CD workflow. The most basic allows configuration splits so development tools are separated from your live site and analytics aren’t running in the middle of development. An Environment Indicator provides titles and color codes each environment to help you avoid acting in errors in the wrong place. The Structure Sync module better coordinates configuration between code and the database. The Stage File Proxy module avoids large and potentially slow database calls during development while still giving you real-world content context while working on your site.
These goodies make it much safer building your website
Safer? I don’t know about you, but even while I am just deep into a practice situation where I have invested a lot of effort, I hate it when I mess up and have to totally start over. Having copies in different environments, and controls on workflow to make sure I test before moving a new something to share with the world, I feel safer with the controlled workflow. GitHub, Platform.sh with its backup procedures, plus our CI/CD Workflow controls, are strong solutions to an enjoyable experience.
———————————————————————————-
10) Putting split configurations in place for each environment brings a need for understanding a little about how Drupal configurations are managed. At the same time, it helps to understand a little about how Platform.sh and Lando create the container environments they provide. A bunch of the container configuration is defined and managed with YAML/YML files. These types of files are used because websites and computer applications in general are often built using a bunch of different languages, and someone was smart enough to conclude it would be pretty cool if there was a common, natural english verbage that could be used for configuration controls. So this is the first level opportunity to tweak what is in our Drupal CI/CD Workflow Project. It has already been done in what will be cloned, so you don’t have to jump in to messing with it further right now. However, if you happen to be building a really large, complex website there are all sorts of things you can do with the container environment control configurations that may benefit you in your Lando local environment but especially your Platform.sh hosted environment.
11) Drupal is basically a PHP application. There are also some very important configuration controls you can manage directly in a key file called php.settings. It is in that file that Drupal is told where to store its configuration YML files. Review that link if you haven’t ever seen this. That portion of the detailed documentation also shows how you export the working configuration of you website into lots of YML files that retain the definitions of various parts within them. It shows doing it with the Administration system GUI and a short cut drush config-export from the terminal command line. Since we will be doing this in our world within the Lando container, we would actually do it as lando drush cex (cex being an allowable short hand for config-export).
12) Since we are planning to have ‘local’, ‘develop’, ‘staged’, and ‘main’ environment situations in our workflow we added additional subdirectories in what you will clone to store YML configuration files that may be unique to how we want to define each one. You will decide what you want to do differently by environment after you clone the project and start doing the GitOps steps. What you bring down to start with is that the tool is in place and the separate buckets to store the definitions are in place. It is worthwhile reviewing instructions on the Configuration Split module as you get into this process and you may even have the tolerance for this solid 55 minute video. Even after you have the basics down, I think you will find that using something like a spreadsheet to get organized in advance of initial set up will help; example template or map.
13) The detailed documentation outlines the installation and php.settings edit process in a step-by-step manner. In this summary, we just jump you to show all those edits; which you would also see in your cloned copy of that file. What you see shows how the configuration is directed into each of those environment split subdirectories, how which environment you are in is automatically detected to line up with the right one, name and color code its display, and instruct stage_file_proxy in the ‘local’ environment where to reach out and grab its content context files.
• Your local ‘new’ project now has all it needs; sort of. It actually has one thing extra and that is the UUID of the new project that is in conflict with the one in the ‘base’ project. So we will now deal with that.
◦ First we are going to find the 'new' project UUID and copy it to our clipboard
◦ Next we are going to go in the /config/sync subdirectory of out Lando copy of the 'base' project we GitCloned locally and find the files with UUIDs. You will edit those files by replacing the old UUID values with the one from the 'new' project instance; you probably are just going to paste over the old value from what you hopefully saved in your clipboard.
◦ Save your work locally in VSCode. Do a lando drush cim to import the files from the /config/sync directory into the local 'active' Drupal project. If all goes as planned, you should have no error for mismatched UUID and things should update.
◦ Having the right stuff where it belongs isn't the end of things, remember that besides those /config/sync files you GitCloned, a bunch of other stuff is different, especially the composer.json file that actually builds the Drupal Project. So run a lando rebuild and after it runs grab one of the URLs, paste it in your browser and bring up the now 'new-but-base-configured' Drupal project. Drive around in it for a while and check things out.
◦ Back in your VSCode IDE go to the Git symbol which by now should have a fairly high number for the files added and changed by the GitClone you did. Select it, do your commit with "message", stage and sync. This should put the updated local project into the 'new projects name' GitHub repository and a minute or two later you can go over to Platform.sh to see that the project has also rebuilt there. Go look at it on the web at the project URL it shows (that is likely still the development URL for the 'main' branch since you have neither assigned an actual DNS nor branched your project yet for CI/CD workflow). Again, check this web version and since the environment_indicator is part of our 'base' project modules and it was configured by our settings.php commands to detect and point to the right "case" in our test syntax, it should show up with a different color bar, bar label, and even favicon color.
Needed: a GitHub Read.me Summary *******