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
file necessary for your WordPress app to run. Because Pagoda Box is a
the auto-installer will not work in the live environment. You should run the auto-installer locally and push the generated
up to Pagoda Box.
If you've never setup a local instance of WordPress, these links will walk you through it:
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
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
The WordPress 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
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.
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:
Use some simple if/else logic in your
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
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
If/Else Logic Based on Environment PHP
With this logic in your
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
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
with your Pagoda
during the deploy process. This technique can also be used for other environment-specific files like your
To get started, create a
directory in the root of your WordPress project and duplicate your
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
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
In order for those changes to apply to your app on Pagoda Box, they must be duplicated in
On every deploy, your local
will be replaced with
Launch Your App!
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
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.
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:
Table of Contents
- WordPress Must be Installed Locally and Pushed Up to Pagoda Box
- Plugins & Themes Should be Updated Locally and Pushed to Pagoda Box
- Don't Specify Plugins & Themes as Network Directories
- Use Environment Variables Instead of Hard-Coding Connection Creds
- Simple If/Else Logic
- WordPress Boxfile with a Custom Environment Variable
- If/Else Logic Based on Environment
- Using a Build Hook to Swap Config Files
- DB Connection Credentials in pagoda/wp-config.php
- WordPress Boxfile with an after_exec Build Hook
- Changes to wp-config.php Must Be Made to pagoda/wp-config.php
If you have any questions, suggestions, or corrections, let us know.