A list of the Pantheon platform considerations for your Drupal or WordPress sites.
This page is used to keep track of common platform considerations, mostly derived from Pantheon's distributed nature. Check back often, as we are keeping it up to date as we make improvements to address these limitations.
Browser Support for Pantheon's Dashboard
In order to focus internal development and engineering work, the Pantheon Dashboard supports the following browsers:
|Versions Supported||Evergreen Browsers - Last 4||Current + Last Year||Internet Explorer 11|
In this or similar instances, consider performing larger operations locally, then importing the code, files, and database back up to the platform.
Batched Data Export to File
In Test and Live environments on plans with multiple application containers, it is difficult to batch export data to a file. Many contrib plugins and modules are not designed to support multiple application containers. It might be possible to get data export working, but that may require additional effort and custom code.
Often, modules and plugins do this type of batch export by continuously appending data to the same file in each request in the batch process. With multiple application containers, the result is that several containers will attempt to add data to the same file at once, while simultaneously syncing their own version of the updated file to other appservers and receiving updates from other application containers. The exported data will likely be incomplete.
A non-batched export of a dataset small enough to complete within the set timeout for web requests will likely work.
Have each request in the data export write to its own
tmpfile, then concatenate these at the end. This solution requires that the Persistent Temporary Path Workaround is in place.
Do small batches and add enough time between each request in the batch process to allow the updated file to be synced between all application containers.
Running the export from the command line using tools like Terminus, Drush, WP-CLI and cron will produce a better result. Larger data sets can be exported, as command line processes have longer timeouts than HTTP requests. For more details, see Timeouts on Pantheon. The export won't need to be batched and can therefore run to completion on a single application container.
Most often, the best solution is to implement data exports as a web service, incrementally exchanging the data with the target system.
Pantheon supports designated use cases for WordPress Site Networks created by WordPress' Multisite feature.
One Application per Site
Each site supports a single Drupal or WordPress application. Placing a WordPress application to behave as the blog for a Drupal site, for example, is unsupported.
Domain Masking or URL Forwarding
Domain masking allows you to serve two entirely different and separate sites over a single common domain. For example, using one system as a front end for marketing efforts and another for blog content:
- Main Site:
Pantheon does not provide any mechanism to implement domain masking. You may be able to setup this using a third party service but Pantheon cannot assist with the configuration or support if you implement domain masking.
In cases of redirection issues on sites with domain masking implemented, Pantheon cannot assist in debugging unless the domain masking is disabled.
While you are able to import an additional database to an environment, only the Pantheon database will be preserved when the application container is updated. This means you can use an additional database for running migration scripts, but should not rely on it nor write any new data to it.
Highly Populated Directories
If you have individual directories with tens of thousands of files (e.g. an image repository) it may be necessary to refactor this file structure to see good performance on Pantheon. The danger zone begins at around 50,000 files in a single directory, and performance drops off suddenly at over 100,000 files.
Drupal itself is capable of managing uploaded content into different directories based on the date or user, which is preferable to dumping all uploads into a single place. Refactoring an existing large-scale site with this issue is usually simply a matter of re-arranging the files and then updating the files table in Drupal.
Consider the File (field) Paths module to help resolve issues with highly populated directories.
Email and Deliverability
Because of the cloud-based nature of Pantheon's infrastructure, we cannot ensure high-deliverability email originating from your Application Containers, as they have no fixed location. While all sites have access to a local Postfix service for testing and development, we recommend using an external SMTP gateway (SendGrid, for example) in production to ensure that your email is delivered.
See the email documentation for more details and suggestions.
Write Access on Environments
For Dev environments in SFTP mode, the entire codebase is writable. However the platform is designed to keep only the codebase under version control. This means that the only writable paths are
sites/default/files for Drupal sites and
wp-content/uploads for WordPress sites.
Any modules for Drupal or plugins for WordPress that need to write to the codebase (and assume write access) need a symlink added so that they will instead write to the file system. For more information, read Using Extensions That Assume Write Access.
However, you can run a great streaming media website. To do so, Pantheon recommendeds that you find a service to handle the transcoding and streaming, whether that's YouTube, Brightcove, Vimeo, Soundcloud, or another provider. These services provide all the necessary components for great streaming media.
It is also possible to deliver smaller media files from Pantheon using progressive download, but the media will not automatically adapt to the bandwidth and capabilities of the device browsing the site, nor does Pantheon support "seeking" to arbitrary playback positions based on time. The actual media formats (encodings, containers, file name extensions) are unrestricted.
Due to the configuration of the Pantheon Filesystem, Pantheon's file serving infrastructure is not optimized to store and deliver very large files. Files over 100MB cannot be uploaded through WordPress or Drupal, and must be added by SFTP or rsync. Files over 256MB will fail no matter how they are uploaded. Transfers with files over 50MB will experience noticeable degradation in performance.
|File Size||Platform Compatibility||Notes|
|≥ 100MB||✔||Can be uploaded via any means|
|< 100MB - 256MB||✔||Must be uploaded over SFTP or rsync|
|< 256MB||❌||Must be hosted via 3rd party CDN|
If you are distributing large binaries or hosting big media files, we recommend using a CDN like Amazon S3 as a cost-effective file serving solution that allows uploads directly to S3 from your site without using Pantheon as an intermediary.
- Drupal sites can use a module such as S3 File System.
- WordPress sites can use plugins such as S3 Uploads or WP Offload Media.
Be aware, even when using an external CDN to host files, you cannot upload files over 100MB through the CMS. Upload these files directly to the CDN (here's Amazon's documentation for uploading to an S3 bucket).
Large Code Repository
When a code repo is larger than 2GB, it increases the possibility of Git errors when committing code on Pantheon. We suggest keeping multimedia assets out of the repo by moving them to a media file storage service such as Amazon S3, and using version control to track URLs.
Rename/Move Files or Directories
Like file directories, files on Pantheon cannot be renamed or moved. Our SFTP mode doesn’t support the
mv command, which is what most apps use when renaming or moving files. The workaround is to delete the old file and upload the new file.
File directories on Pantheon's file serving infrastructure cannot be moved or renamed. The workaround is to create a new directory, move all the files from inside the old directory into the new one, and delete the old directory.
IP-Address Based Security Schemes
IP-based security is not recommended on Pantheon - or any cloud platform because the actual IP address where code executes from can change as application containers are migrated throughout the infrastructure.
For more information, see Dynamic Outgoing IP Addresses.
Pantheon may send a generic Maintenance Mode message during platform problems; this message cannot be customized.
Built-in Maintenance Mode for both Drupal and WordPress sites can be customized; clear caches when toggling.
Server Side Includes (SSI)
Pantheon does not and will not support Server Side Includes. We recommend converting those to use PHP includes.
PHP Short Tags
PHP short tags (
<? ... ?>) are not supported on Pantheon. The PHP Manual recommends not utilizing short tags because they are not supported on every server. Additionally, using short tags can interfere with embedding PHP in XML. Avoiding their use leads to more portable, re-distributable code.
For sites that need to provide services with Cross-Origin Resource Sharing (CORS), adding the proper header should enable the resource. See https://enable-cors.org/server_php.html
Sites that consume services using CORS, such as Amazon S3 CORS, do work on Pantheon.
Large (>100GB) File Backups
Large backups take longer, use more resources, and have a higher likelihood of failing. Additionally, a 100GB tarball is in itself not particularly convenient for anyone. For this reason, scheduled backups do not backup files for sites with footprints over 200GB (although code and database are backed-up as normal). Despite the lack of backups, file content is highly durable and stored on multiple servers.
Pantheon does not currently support LESS or Sass/Compass CSS preprocessor languages. LESS and Sass will need to be pre-compiled to make traditional CSS stylesheets before being pushed to the platform.
Pantheon sites use NGINX to concurrently serve requests. The NGINX web server ignores distributed configuration files such as
.htaccess for reduced resource consumption and increased efficiency. This configuration is standard across all Pantheon sites, and modifications to the
nginx.conf file are not supported.
For details, see Configure Redirects.
Drupal False Positive
Drupal 7 and 8 checks for arbitratry code execution prevention by looking for a specific string in the
.htaccess file. Since Pantheon uses NGINX as described above, this message can be safely ignored. For more details, see this Drupal.org issue on
Pantheon does not currently support modifying the nginx.conf per site, as we run a highly tuned universal configuration file. All of the containers run a standard profile, and we have opted to keep this configuration to keep the nginx.conf lean.
Database Stored Procedures
MySQL stored procedures are not supported. Due to the nature of the platform, there is no guarantee that they will persist following a database migration. You can avoid the use of stored procedures by using parameterized queries or object-relational mapping.
Oracle Database Drivers
Pantheon does not currently support directly connecting to Oracle databases. Customers have successfully used the Pantheon Enterprise Gateway to connect to an external API on top of their Oracle databases.
Pantheon does not currently support the PHP/Java Bridge.
General PHP Framework Support
Pantheon does not currently support any PHP frameworks outside of Drupal and WordPress. The platform is only optimized for Drupal or WordPress and no others. Although PHP will run, we can not assist you in getting the non-approved frameworks running in any way.
Node.js is not available in the platform. If running node.js services is a hard requirement for your Drupal or Wordpress application, the node.js service must to be hosted on a different remote server outside of Pantheon.
Modules and Plugins with Known Issues
See Modules and Plugins with Known Issues for a list of Drupal modules and WordPress plugins that are not supported and/or require workarounds.
Inactive Site Freezing
Sandbox sites that are over four months old that have not had code commits or other Git activity for three months are "frozen". All requests to a frozen site will return a
530 Site Frozen error code, and the site's Dashboard will be unavailable.
You can reactivate a site with a single click. Simply visit the site's Dashboard and click Unfreeze site. Within a few minutes, the site will be ready for development again. If you experience any issues, a backup of the site is available and can be restored via the Site Dashboard.
Emoji support is available out of the box on WordPress and Drupal 8. Drupal 7 sites can enable Emoji support by following this procedure:
For new or existing Drupal 7 installs, add the following lines to
$databases['default']['default']['charset'] = 'utf8mb4'; $databases['default']['default']['collation'] = 'utf8mb4_general_ci';
Existing sites that already have an active database must install the UTF8MB4 Convert Drush command and convert the database. Note that this is not a Drupal module that can be enabled, it's a Drush command that should be placed within
/sites/all/drush. Once you've installed the command in
/sites/all/drush, you must clear Drush cache for the new command to run. Clear Drush cache using Terminus:
terminus drush <site>.<env> -- cc drush
Start by making a backup of the site database, then place the site in maintenance mode and run the following:
terminus drush <site>.<env> -- utf8mb4-convert-databases
This will convert the database tables in the existing installation to the proper encoding to support emoji characters. After making the conversion, test it out by placing an emoji in the site text.
Terminus, our command-line tool for power users, is designed for 'nix-type operating systems like MacOS and Linux. While some people have installed Terminus on Windows using the Git BASH on Git for Windows or Windows Subsystem for Linux shells, this is not officially supported.
If you're a Windows user, consider using a virtualization tool like VirtualBox to run a virtualized 'nix-type environment for tools like Terminus.