Recently we migrated a client to Pantheon, a move made possible by Pantheon’s custom upstream functionality. Pantheon’s Fastly CDN integration also enabled the handling of some specific site requirements and now the sites are performing better than ever. Here is a short overview of creating and managing custom upstream sites.
Creating the Upstream Repo
Custom upstreams make it easy to stream-line deployment for multiple sites while maintaining the option of site-specific code. Need a module available for all sites? Add it to the upstream repo. Need one for just a single site? Push that to the site’s repo.
Using an upstream repo does come with a little extra overhead. The upstream repo must be maintained on a 3rd party service and if you make site-specific modifications you have to be careful not to create conflicts with the upstream code. Pantheon does its best to manage and resolve code conflicts but you can still create issues that will hold up deployment.
One of the most important points is to not use the upstream repo to deploy Drupal core updates. Instead you must set Pantheon’s core updates repo as an upstream for your own upstream repository in order to merge the core updates to your upstream.
git remote add pantheon-drops-7 git://github.com/pantheon-systems/drops-7.git
Another nice addition for upstream configuration allows you to set default values for site config using the pantheon.upstream.yml and pantheon.yml files. This allows you to protect web paths (Pantheon uses the Nginx webserver so htaccess files are not supported), change your site’s docroot, do PHP version control, and more.
Once the upstream repository is created you can start creating new sites very easily. Navigate to the Upstreams tab in your organization’s dashboard and click “Create Site from Upstream.”
This creates a new repository already linked to your custom upstream. If you have an existing site you would like to switch to the upstream you can do so with Pantheon’s Terminus tool. However, please heed their warning
Switching the upstream of an existing site is risky. Consider creating a new site from your Custom Upstream and migrating the contents. If you must switch upstreams, back up your site first, and consider our documentation on upstream merge conflicts.
Once you have your repositories created you can then import your site’s database and files folder. If you have ssh access on your existing site’s server you can use secure FTP or drush rsync to transfer the files to Pantheon with a command from your site’s docroot such as:
drush rsync --verbose sites/default/files/ @pantheon.site.dev:%files/
When you initially create a Pantheon site you create the dev environment, so I suggest you use your site’s live database and files to set up the dev site. Then create the test and live environments. They will be created from the up-to-date dev database and files.
Managing Multiple Sites
Now that you can deploy code using the custom upstream repo you might wonder about making the rest of the process easier. If you don’t want to click a few hundred times to manually deploy your updates through dev/test/live on all sites, or if you don’t want to log in to every site to update some config, then you’ll want to look into using Terminus plugins.
For our relatively simple needs we used the following two plugins.
- Mass Update - https://github.com/pantheon-systems/terminus-mass-update
- This lets you push your upstream repo changes to every site’s dev environment by piping in a list of sites that use your custom upstream into the mass-update plugin.
-
terminus site:list --format=list --upstream [your_upstream_dashboard_ID] | terminus site:mass-update:appl
- Mass Run - https://github.com/jnettik/terminus-mass-run
- This plugin makes it easy to run various commands across your sites such as Drush commands or dashboard deployments to a specific environment.
-
terminus site:list --format=list --upstream [your_upstream_dashboard_ID] | terminus remote:mass:drush --env=live – [your_drush_command]
Notes: There were a few minor blockers we had to work around
File Folder Setting - Site’s using the Performance Medium or higher service use a virtual container environment which can cause temporary files issues as detailed in Pantheon’s temporary path workaround. Their documented method did not work for our sites as the database management tool Pressflow was overriding the updated configuration.
Mass Deployment - The Terminus plugins were constantly failing during the migration process. However these issues went away once all the sites were set up and every environment was in sync with no pending deployments. If you run into any issues go through your site dashboards and make sure everything is properly set.
Redis / Solr - If you use Redis, Solr, or other services you will need to enable those for every site using them. Otherwise you will likely run into critical errors. Don’t forget to update your search config to use Pantheon’s Solr instance!
