Use the Pantheon Workflow

Understand the Pantheon workflow, and how to use separate Dev, Test, and Live environments for your Drupal or WordPress sites.


Note

This page offers a high level description of the intended usage of Pantheon's Dev, Test, and Live workflow. After familiarizing yourself with the concepts described here, follow our step-by-step Quick Start Guide to practice the basics.

Every Pantheon site comes with three environments: Dev, Test, and Live. Each environment runs a version of the site on its own container. Separate Dev, Test, and Live environments allow you to develop and test your site without impacting the live site's availability to the world. Additional development environments are available with Multidev.

Get DevOps Training

Optimize your dev team and streamline internal workflows. Pantheon delivers custom workshops to help development teams master our platform and improve their internal DevOps.

Components of a Site

One of the core concepts at the heart of the Pantheon workflow is the distinction between code and content.

Code

Code refers to anything version controlled by Git which includes core, custom and contributed modules or plugins, themes, and libraries.

The codebase is comprised of the following files and directories:

├── index.php
├── wp-activate.php
├── wp-config.php
├── wp-comments-post.php
├── wp-blog-header.php
├── wp-admin
├── wp-cron.php
├── wp-load.php
├── wp-links-opml.php
├── wp-includes
├── xmlrpc.php
├── wp-trackback.php
├── wp-signup.php
├── wp-settings.php
├── wp-mail.php
├── wp-login.php
├── wp-content
    ├── index.php
    ├── mu-plugins
    ├── themes
    ├── plugins
├── includes
├── index.php
├── misc
├── modules
├── profiles
├── scripts
├── sites
    └── all
       ├── modules
       └── themes
    └── default
       └── settings.php
└── themes

Content

Content refers to your sites files and the database. In this context, files are static images and assets stored in the standard upload path wp-content/uploads for WordPress and sites/default/files for Drupal.

Code Moves Up, Content Moves Down

Dev Test and Live icon

The main process of the Pantheon workflow is to move code up from Dev to Test to Live and content down from Live to Test to Dev. To facilitate this, we put files into our distributed filesystem, Valhalla, and code on to the application containers. When you build or migrate your site to Pantheon, configuring the correct paths initially will avoid complications down the road.

Why does Pantheon do this?

Pantheon is an "opinionated platform". Specifically, we're of the opinion that version control is a critical component when building and maintaining a website. We've built a platform tailored specifically to let you use version control to maintain all of your code, keep all of your files separate, and have all the test beds you need to make sure everything works before changes hit production.

Commit Code in Dev

Code is writable in the Dev (or a Multidev) environment, but is locked in Test and Live. This is intentional, and supports the workflow model we've described. Update code in the Dev environment via SFTP or Git. For more detailed information on developing directly in SFTP mode, please see the guide.

Combine Code from Dev and Content from Live in Test

When you're ready to test a new set of changes, deploy your code from Dev. At this point, you will be prompted to clone your content from the Live database. This combines the code from Dev and the database values from Live in the Test environment to be absolutely certain that your deployment to Live will go as planned. Deploys are performed by adding a git tag to the last commit on the Test environment.

Once changes are pushed to Dev, the Deploys panel in the Test tab will prompt you to commit the changes to Test:

Site dashboard, test environment, Deploys section

  • The Deploy Log helps you group a batch of commits into a single deployment. Best practice is to keep logical groups of edits together and then summarize those groups with a single deployment message.

  • Check the Pull files and the database from the Live environment? Checkbox to pull the content from your Live site to the Test environment.

  • Drupal site deploys come with the ability to run update.php after code deploys. hook update n and any other necessary database updates will be made automatically on the Test environment.

    On WordPress site dashboards, cloning the content will expose an option to convert URLs from the Live environment's pattern to the Test environment's, including the protocol from HTTPS to HTTP for encrypted live environments.

After running this operation, be sure that:

  • Your database updates succeed
  • Your exported configuration is in place
  • The site is functioning as expected in the Test environment

It's also a good idea to review the Status tab and run Launch Check, and make sure everything looks good. For details, see the following:

If there are additional manual "go live" instructions, now is a good time to review them and make sure they work and are properly documented.

This may be a good time to run regression or smoke tests by stepping through your main workflows manually, or by running an automated test suite. Use Test to make sure that everything is working correctly before deploying to Live.

This entire process is designed around making sure that the Live site is always stable and never at risk due to code updates.

Deploy Code to Live

After testing your changes you can take them live. Deploying code from Test to Live will immediately update your live website; however, static assets such as images and css may still be outdated. To update them, check the Clear Caches option when deploying changes to your Live environment. For more details, see Clearing Caches for Drupal and WordPress.

Site dashboard, live environment, workflow section

Configuration Management

Dealing with changes to your site's configuration, stored in the database, can be a challenge. Moving the database up from Dev to Test and Live typically won't work, because it will overwrite content in Live. While you can make manual configuration changes on each environment, it's a best practice to manage configuration in code.

WordPress

Drupal

Understanding Write Permissions in Test and Live

By design, code changes via SFTP are prevented in Test and Live. All code changes should be done in Dev. There are two ways to update code in Test or Live:

  1. Use the Workflow (Recommended): Deploy code from Dev to Test to Live via the Site Dashboard as outlined above.

  2. Hotfixes: Hotfixes is not a best practice and should be the exception, not the norm. Pushing a hotfix via Git is the only way to push code changes directly to Live without deploying through Dev and Test.

Managing Database and Files: Clone, Import, Export, Wipe

You may also clone, import, export, and wipe the database and files per environment. Wiping completely resets the database and files, but leaves the codebase intact. This means you will lose all data and will need to either re-import, or re-install to get your site back online.

The database clone operation excludes some tables by default. The excluded tables are: cache, cache_block, cache_bootstrap, cache_field, cache_filter, cache_form, cache_image, cache_menu, cache_page, cache_path, cache_update, cache_views, cache_views_data, accesslog, and watchdog. You can clone databases from one environment to another at any point. It does not need to only be within the deployment process.

Note

The Export tool does not include a copy of the site's codebase and cannot be used as the basis to create a new site. Use the archive files generated by the Backups Tool if you wish to create a new site.

Uncommon Workflows

Typically, you'll create content in the Live environment. However, when deploying a newly-built site for the very first time, it is often necessary to push the content "up", which is the opposite of the normal content workflow. In this case, you may move the database and files (e.g. images) from Dev or Test to Live via the Database/Files > Clone area of the Dashboard.

Moving content up to Live should almost never be done on a launched site. The only exception is if that site is 100% read-only, as pushing the database and files will overwrite all changes made. Also note that overwriting the database of a live site may cause downtime.

If there are other workflows you would like to see, contact us. We're always looking for ways to improve the platform.

Troubleshooting

Uncaught Exception: Table 'pantheon.semaphore' Doesn't Exist

If you access the site before a database import is complete, you may see the following error:

Uncaught exception 'PDOException' with message 'SQLSTATE[42S02]: Base table or view not found: 1146 Table 'pantheon.semaphore' doesn't exist'

MySQL imports tables sequentially, in alphabetical order from A to Z. If you access the site before the operation is complete, Drupal will try to bootstrap, and the MySQL import may be at the table letter G, for example, and the result is the semaphore table does not exist error. Once the import or clone operation has finished, the error should no longer appear.

See Also