Last Updated December 2014

Getting WordPress up and running on Pagoda Box is pretty simple, but there are a few things to be aware of. After reading this, you should be able to:

  • Launch a WordPress app on Pagoda Box
  • Bask in the combined awesomeness of WordPress and Pagoda Box

Before You Get Started

Pagoda Box is not your traditional hosting environment. The Understanding the Environment doc walks through all of the specifics, but a few of the differences directly affect the WordPress workflow you're probably used to.

WordPress Must be Installed Locally and Pushed Up to Pagoda Box

The WordPress auto-installer generates the wp-config.php file necessary for your WordPress app to run. Because Pagoda Box is a read-only environment, the auto-installer will not work in the live environment. You should run the auto-installer locally and push the generated wp-config.php up to Pagoda Box.

If you've never setup a local instance of WordPress, these links will walk you through it:

Create a local WordPress instance on a Mac
Create a local WordPress instance in Windows

Plugins & Themes Should be Updated Locally and Pushed to Pagoda Box

Updating plugins and themes is typically done through FTP and files are written directly to the filesystem. Because this Pagoda Box is read-only, this workflow will not work in the live environment. All plugins and themes should be managed and updated locally, then pushed to Pagoda Box.

Don't Specify Plugins & Themes as Network Directories

Some users have attempted specifying the wp-content/themes and wp-content/plugins directories as network directories to be able to update themes and plugins in the live environment. This does provide the desired functionality, but we highly discourage it for reasons covered here.

The WordPress Boxfile

The Boxfile is a simple YAML file that houses the configuration for you app's environment. For a base WordPress install, all you need is a web service with wp-content/uploads listed as a shared asset directory along with a mysql database service.

Basic WordPress Boxfile YAML


When you deploy your Boxfile, the MySQL database will be created and WordPress will have the ability to upload and store content.

If there are other specific configurations settings you need, check out the Boxfile and PHP Settings in the Boxfile docs for information.

Modify Your WP-Config to Work in Multiple Environments

When working with a single WordPress codebase that needs to function in two different environments (your local and on Pagoda Box), there's some techniques you can use to make the transistion between the two seamless. The main issue you run into with Wordpress is having to connect to two different databases. There's two very simple ways to adjust your app so you don't have to modify the connection details between each deploy:

  1. Use some simple if/else logic in your wp-config.php.

  2. Using a build hook to swap config files.

Use Environment Variables Instead of Hard-Coding Connection Creds

This isn't required, but we recommend using environment variables in place of connection credentials. Whenever a database is created on Pagoda Box, environment variables are automatically generated for each connection credential. All the code samples in this doc will use these environment variables.

Simple If/Else Logic

This method consists of including both sets of connection credentials in your wp-config.php and determining which set to use based on the environment the app is running in.

The first thing you want to do is add a custom environment variable to your Boxfile. This variable is what will tell your app that it's running on Pagoda Box. This along with the Basic WordPress Boxfile settings would like the following:

WordPress Boxfile with a Custom Environment Variable YAML


Now, use your custom environment variable to create some simple if/else logic inside wp-config.php.

If/Else Logic Based on Environment PHP


With this logic in your wp-config.php, your app will connect to the correct database whether you're working locally or on Pagoda Box.

Using a Build Hook to Swap Config Files

Build Hooks allow you to "hook" into your app's build process and run scripts or commands. Using an after_exec hook, you're able to modify your source code before it's deployed. For a deeper dive into deploy hooks, check out the Build & Deploy Hooks doc.

With this technique, you need to have two wp-config.php's in your repo. One to be used locally and the other to be used on Pagoda Box. You then use an after_exec build hook to replace your local wp-config.php with your Pagoda wp-config.php during the deploy process. This technique can also be used for other environment-specific files like your .htaccess.

To get started, create a pagoda directory in the root of your WordPress project and duplicate your wp-config.php into the new directory. Replace your local database connections credentials with your Pagoda Box database connection credentials:

DB Connection Credentials in pagoda/wp-config.php PHP


Add an after_exec build deploy hook to your Boxfile that will replace your local wp-config.php with your pagoda/wp-config.php

WordPress Boxfile with an after_exec Build Hook YAML


Changes to wp-config.php Must Be Made to pagoda/wp-config.php

Many settings you're able to specify your in your WordPress Admin actually modify the wp-config.php. In order for those changes to apply to your app on Pagoda Box, they must be duplicated in pagoda/wp-config.php.

On every deploy, your local wp-config.php will be replaced with pagoda/wp-config.php.

Launch Your App!

With your wp-config.php now portable across your local and Pagoda Box environments, you're ready to deploy your WordPress app. The Launching an App doc walks through the different ways of getting your app up and running.

Migrate Your Existing Database

If you have a database full of posts, comments, links, etc., migrating your data to your new app on Pagoda Box is simple. The Migrating Existing Data covers everything you need to know.

Migrate Your Writable Storage

Because wp-content/uploads is specified as a network directory, the contents of that directory within your repo won't be recognized by your app on Pagoda Box. The Network Storage doc explains why. But once your app is deployed, you can manually upload the contents of your uploads directory to your shared asset storage through and SSH/SFTP connection. The Managing Network Directories section in the Network Storage doc will walk you through it.

Configure Session Handling

Because apps on Pagoda Box are distributed accross multiple servers, the say sessions are handled may be different than what you're used to. The PHP Session Handling doc provides the details and offeres options for how to handle sessions in a distributed environment.

Helpful Resources

Now that your WordPress app is up and running on Pagoda Box, there's a few more things you can do to get it fully functional. These docs will help:

Sending Mail from Your App
Using Custom Domains
How & When to Scale

If you have any questions, suggestions, or corrections, let us know.