Neatly Organizing Your WordPress on Pantheon Hosting

In the digital realm, maintaining order and organization can be as satisfying as tidying up a physical space. For those like me who appreciate neatness, keeping WordPress core files in a dedicated subdirectory is a preferred practice. However, when it comes to Pantheon managed WordPress hosting, achieving this can be a bit challenging. In this guide, we’ll explore the concept of “WordPress in its Own Directory” on Pantheon and provide you with a solution to implement it seamlessly.

Understanding “WordPress in its Own Directory”

If you’re unfamiliar with the concept, “WordPress in its own directory” involves placing all core WordPress files and directories (such as wp-includes and wp-admin) inside a subdirectory within your website’s document root, rather than having them directly in the document root itself.

This approach offers several benefits:

1. Enhanced Organization

- A cleaner and more organized file structure for those who value aesthetics and order.

2. Improved Security

- The ability to configure your web server to restrict unauthorized access to the WordPress directory, enhancing security. (Note: This may affect WordPress auto-updates.)

3. Compatibility with Composer

- Simplified management of WordPress core and plugins when using Composer, particularly when they are contained within a subdirectory.

Let’s delve into the steps to achieve this on Pantheon.

Step 1: Setting the Stage

Before we proceed, let’s establish some assumptions and prerequisites:

Assumption 1: web_docroot Configuration

I assume you have configured your pantheon.yml file with web_docroot: true, which sets the document root to /code/web instead of just /code. This is for better organization and security.

Assumption 2: Subdirectory Naming

We will use the subdirectory named wp/ to house WordPress core files. You can choose a different name if you prefer, but for consistency, we’ll stick with wp/ in this guide.

Assumption 3: Website Name

For convenience, we’ll refer to the website as “mysite.”

Assumption 4: Upstream

I’m using an empty WordPress upstream for all Pantheon sites. If you use Pantheon’s default WordPress upstream, you may need to adjust these instructions accordingly.

Assumption 5: Technical Proficiency

This guide assumes a certain level of command-line Linux proficiency, including git cloning and symbolic linking.

Step 2: Moving WordPress to Its Subdirectory

Let’s begin the process of relocating WordPress to its own directory:

  1. Clone your Pantheon site (e.g., mysite) onto your local machine using git clone.
  2. Create a directory within the web/ directory for your WordPress files. We’ll call it wp/.
  3. Move all WordPress core files and directories (e.g., wp-admin, wp-includes, etc.) into the newly created wp/ directory. Ensure you include files like index.php, license.php, and readme.html. Notably, exclude wp-config.php and wp-content/ for now.
  4. Copy (do not move) the index.php file from the web/ directory, and modify the last line to read:
    require( dirname( __FILE__ ) . '/wp/wp-blog-header.php' );
  5. Locate the wp-config.php file. Since Pantheon provides a customized wp-config.php, keep it in the web/ directory (outside of wp/).
  6. In your wp-config.php, find the line starting with define('WP_SITEURL', and modify it to read:
    define('WP_SITEURL', $scheme . '://' . $_SERVER['HTTP_HOST'] . '/wp');
  7. After the define('WP_SITEURL'… line, add these two lines:
    define( 'WP_CONTENT_DIR', dirname( __FILE__ ) . '/wp-content' );
    define( 'WP_CONTENT_URL', WP_HOME . '/wp-content' );

Now, you can test your website on your development environment. If it works correctly, proceed to test it on the staging environment and finally on the live site.

Step 3: Configuring wp-cli.yml

During my transition to Pantheon, I encountered issues with cache clearing when using “WordPress in its own directory.” To resolve this, I discovered a crucial configuration file: wp-cli.yml. Follow these steps:

  1. Run the cache-clearing process using Pantheon’s command-line tool, terminus:
    terminus env:clear-cache mysite.live
  2. If you receive an error indicating, “This does not seem to be a WordPress install,” it’s likely a wp-cli error.
  3. To address this, create a file named wp-cli.yml in the root (code/) directory of your Pantheon project with the following content:
    path: web/wp

This file specifies the path to your WordPress installation within the wp/ subdirectory.

Step 4: Resolving Plugin and Theme Issues

You may encounter issues with wp-cli commands related to plugins and themes. To address this, create a symlink to your wp-content/ directory within the wp/ directory:

mysite/web/wp$ ln -s ../wp-content wp-content

Commit this change to your Git repository and push it to your Pantheon repository. Then, deploy these changes through the Pantheon dev/test/live workflow.

With these adjustments, running wp-cli commands like terminus wp mysite.live -- plugin list should now provide a complete list of your plugins and themes.


While the process of organizing your Pantheon installation with “WordPress in its Own Directory” may not be extensively documented, it is a valuable technique for those who appreciate digital neatness. I hope this guide has helped you achieve a cleaner, more organized WordPress setup on Pantheon. It’s worth noting that Pantheon has shown interest in improving documentation for this approach, so stay tuned for potential updates.

If you’re a perfectionist when it comes to digital order, implementing these steps can significantly enhance your Pantheon hosting experience, ensuring everything is in its rightful place and functioning correctly.

© 2013 - 2024 Foreignerds. All Rights Reserved