Table of Contents
Tools
You will need git, composer, php. Use the links below to install or use UMD Virtual Workspace which has the necessary tools installed.
Create a SSH key certificate to checkout your site code from Pantheon.
From a terminal window, run the command:
ssh-keygen -b 2048 -t rsa
- This command works on Linux, MacOS, and Windows 10.
Unless you have reason to change it, leave the default location of ~/.ssh/id_rsa as is. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.
A passphrase is recommended to provide greater security, but can conflict with tools that cannot handle them.
Copy the SSH key
Once the files are created, you will need to copy the contents of id_rsa.pub to your clipboard.
Linux and Mac users can cat the file to the terminal and copy the output:
cat ~/.ssh/id_rsa.pub
Windows users can achieve the same result with type:
type .ssh\id_rsa.pub
Cut and paste the certificate into Pantheon, this is done under your account page.
Site code checkout
To update the code for your site, first you will have to check out the code to your local computer.
Download site code
From your sites Pantheon dashboard, you will find the button "Connection info" on the upper right.
Clicking on the Connection Info button will bring up information for your site, for this work we are interested in the top info block, the Git SSH clone url.
In the Pantheon Connection info window, locate Git → SSH clone url. You will copy this value after choosing where to store the site code on your computer.
Choose where to store your site code
Within your terminal you are ready to paste the SSH clone url, but first it is useful to decide where you would like to put the site code. As most terminals default to your user directory, it can be useful to create a folder to store your site code downloads, to help organization. If you would like to make a new directory, you can use a command like:
mkdir sitecode
This creates a new directory called 'sitecode' within your user directory, you can name the directory whatever you would like.
Changing into that directory
Once you have created your new site code folder, or alternatively if you would like to use an existing directory such as your Documents folder, you will then need to change into that folder with the 'cd' command followed by the directory name:
cd Documents
The 'cd' command is for changing directories, then the name following is the directory you want to change to, in the above command the Documents folder. If you had made a new folder called 'sitecode' instead, you would use the command:
cd sitecode
Clone your site code
Once you have chosen where you would like to store your site code and changed into that directory, return to the Pantheon Connection info window. Under Git, use the copy button next to SSH clone url, shown earlier.
Paste the copied command into your terminal and press Enter. The command will begin with:
git clone
Git will begin downloading a copy of your site's code to your computer.
You will likely be asked to confirm the connection if it is your first time checking out the code, type 'yes' when prompted.
When the checkout is finished, Git will create a new directory containing your site's code. The directory name will be shown by the clone command. Before running the Composer or Git commands in the following sections, change into that new directory, it will likely end with -umd:
cd example-umd
You can confirm that you are in the correct directory by running:
git status
If you are in your site's Git repository, Git will show the current branch and repository status.
Pantheon Composer build process
Once your site code is checked out, you're ready to start making updates. Code updates to Pantheon sites are based on using the PHP tool Composer. Composer is a package manager, you tell it what modules you want or don't want on a site, or to check for updates, and Composer does the work without you having to manually find individual projects, files or dependencies.
Before starting
Before starting any code updates, it is highly advisable to make sure you are in sync with the server and have all the latest changes. Failure to be in sync can lead to your commits being rejected by the server.
Before making changes, confirm that you are in your site's repository:
git status
Git should display the status of your repository without reporting that it is not a Git repository.
Next, retrieve the latest changes from Pantheon:
git pull
This command gets all the latest changes from the server
Update packages managed by Composer
To check for and apply updates allowed by the versions specified in your site's Composer configuration, run:
composer update
This command will run the composer.json file, and build out the composer.lock file, downloading and installing all specific modules and dependencies that are listed as needed for the site. If you do not wish to install all the files locally, you can run composer update --no-install. Any updated versions since you last ran this will also be grabbed.
Add a module
If you would like to add a module, you can do so with the 'composer require' command, ex:
composer require drupal/admin_toolbar
drupal/admin_toolbartells composer what repository the package is in, in this case drupal, and what exactly to install, in this example admin_toolbar
composer require command above. The following options may be useful when a specific module requires additional dependency or version handling.composer --ignore-platform-reqs -W require drupal/admin_toolbar:^3
- --ignore-platform-reqs allows you to avoid local platform compatibility, the site will be built on Pantheon so this allows you to avoid any local issues
- -W is a shortcut for --with-all-dependencies, this pulls in all dependencies and requirements for a module, not just the module itself
- :^3 is a version constraint. Without a number listed, composer will get the latest version available that is allowed with your existing constraints. In this example, ^3 tells composer to get the lastest version on the 3.x branch, but not anything above the major version 3. In most cases, letting composer install the latest version is best practice, but in some cases it may be necessary to limit the versioning. Do note, limiting the versioning with a :^x means composer will never update the module past x automatically. When an update is eventually desired, composer.json must be edited to update the constraint.
Remove a module
Before removing a module's code, uninstall the module through Drupal so that its configuration can be removed correctly.In your Drupal site, go to Extend → Uninstall, locate the module, and follow the uninstall process.
Find the module in the list or via the search box, check its checkbox, and scroll all the way to the bottom of the page and click the 'uninstall' button. Confirm that this is the module you want to remove (including all of its content), and click 'uninstall' again.
Once the modules configuration and content has been removed, you can remove the code of the module with:
composer remove drupal/admin_toolbar
Add libraries via composer
Adding libraries is possible via composer, this allows composer to download and install the library files, freeing you from having to manage them. Adding libraries to the composer.json is a bit more complicated then adding a module, detailed documentation can be found on the Drupal page.
Commit and push
After installing and/or removing all modules with composer, and running composer update, you are now ready to commit your changes to the site repo and push them back to the Pantheon server to be build. From your git GUI, you should see files that have been changed, if you are still within the terminal, run the command:
git status
This will show you all the files that have changed. In general, you will see changes to the composer.lock file as the most often changed as this is the file that lists all your modules and specific info about them. Other likely changes are composer.json itself if you changed it manually.
Adding your changes with git add:
git add file_name
So if your git status reported that composer.json and composer.lock had changes, you would would run:
git add composer.json composer.lock
Once you have added your changes, you are ready to make a commit. Commits are the individual set of changes you are making.
Commit the changes to composer.json and composer.lock with:
git commit -m "your message here"
Give the commit a message describing what changes were done between the "".
- the -m command is for leaving the commit message
Once you have committed them, you can push your changes to Pantheon with the command:
git push
Once you push your changes, Pantheon will run the composer.json on their servers, and the changes will be deployed to the dev version of your site for review.
Testing the dev environment
Once the changes have been pushed to the main branch and built on the Pantheon servers, they will appear on within the dev site environment. The dev site should be then tested to make sure the changes work as expected, and everything is still correct with the site.
For the testing, you are not looking at content, as it will likely be out of date on the dev site, instead you want to review functionality.
If you were just doing maintenance updates, then you will just need to review to make sure your site still functions as the live site does. Clicking around to a few pages should be sufficient to make sure they still load and display.
If the site had encountered bigger errors, the entire site will be white and display nothing. If that happens, first add the following to the dev site url:
update.php
your url bar will look something like:
https://dev-drupal-umd.pantheonsite.io/update.php
you can run the maintenance database updates from this url, which will often fix blank white screen issues.
Updating the Test and Live environments
Once this testing is completed, the changes need to be pushed to the test environment, and finally to the live environment so that the public facing site receives the updates. To deploy the updates, click on the 'Test' tab on the site Pantheon dashboard, the first pane there should be the deploy section. You will see a list of changes that will be deployed, and a box for deploy messages. Write a message as desired, and click the 'deploy code' button. Once the code has been deployed on the test instance, repeat the same process for the live environment via the "Live" tab.
Resources
Update Drupal Core and Modules
After migrating to the Pantheon platform, the responsibility of keeping Drupal core of the site up to date has shifted to the site owner.
According to the USM Security policy each site should be updated with any security patches in a timely manner. Drupal.org’s general policy is to release scheduled security patches on the third Wednesday of every month, therefore it is imperative for site owners to regularly check for security releases and deploy them to their Live environment.
Pantheon has helped to ease this burden with two features: AutoPilot and Check Now.
AutoPilot
Pantheon has provided the “AutoPilot” feature which checks for and updates all Drupal modules, including the core, using integrated composer. AutoPilot also performs visual regression testing, and then finally merges the code into the site’s Development environment if no issues have been found. AutoPilot is configured to run every 7 days, therefore it may be up to seven days after a new version is released before AutoPilot runs and merges updates of Drupal modules into the Development environment.
DIT will ensure that AutoPilot is configured and runs successfully in Development, engaging Pantheon support as needed. Site owners should regularly deploy updates from Dev to Test and Live to ensure that Drupal core and modules are kept up-to-date.