Moving Your App to Pagoda Box

Last Updated October 2014

So you have an application hosted somewhere and you're looking to move it to Pagoda Box. This doc will walk you through everything you need to do to make sure that transition goes as smoothly as possible. By reading it, you should be able to:

  • Easily transition your app to Pagoda Box
  • Bask in the awesomeness of Pagoda Box

The Basics

Many of the basics of Pagoda Box that could be included in this doc are already covered in other docs, so to avoid duplicating content, we'll just provides links to pertinent information.

One doc we highly recommend reading up front is Understanding the Environment. Pagoda Box is very different from a traditional hosting environment, and may require some adjustments to your application. Understanding the Environment will walk you through what you need to know.

Turn Your Domain's TTL Down

The first thing you should do to move your app to Pagoda Box is contact your DNS provider and change your Time to Live (TTL) to as low as you possibly can. This should be done at least 48-72 hours before you plan to point your domain to your app on Pagoda Box. This will minimize any downtime caused DNS propagation.

Create Your Boxfile

The Boxfile is a simple YAML file that houses all of the configuration for your app and is required to launch an app. In your Boxfile, you tell Pagoda Box what services your app needsEverything from your PHP version to PHP extensions and database/cache type(s) are handled in the Boxfile. It should be placed in the root of your app's repo. For more information, check out the Boxfile documentation.

Launch Your App

Launching your app is a simple process. Everything you need to know is covered or referenced in the Launching an App doc.

Migrate Your Writable Directories

Because apps on Pagoda Box are distributed across multiple servers, writable permissions must be handled differently. For all the details, check out the Network Storage doc.

In short, you need to create a Network Storage service to house read/write directories, then specify those directories as network directories. Once your network storage service has been created and network directories have been specified in your Boxfile, you will need to manually migrate any files already existing inside those directories to your storage service. How to do this is covered in the Network Storage doc.

Migrate Your Database(s)

If your app is currently using a database, you will need to create a new database on Pagoda Box and migrate your data.

Creating a database on Pagoda Box is done in a few simple steps. It can be done in your dashboard or in your Boxfile. To create a database through the dashboad, click the "Add a Data Service" button and select the type of database you need. To create one from your Boxfile, include a database service with the type set to whatever type of database you need. On your next deploy, your database will be created.

To connect to your database, you can either hard-code the connection credentials found in your dashboard, or you can include the auto-generated environment variables in your codebase.

Once your database is up and running and your app is connecting to it, you can migrate your existing data.

Setup Email (Optional)

If your app needs to send mail, you'll need a 3rd party SMTP provider and a few credentials to put into your app dashboard. The Sending Mail doc will give you all the juicy details.

Add Your Custom Domain

You can use your custom domain(s) by adding any necessary DNS aliases for your app. The Using Custom Domains doc will walk you through it.

Wait to Change Your A-Record

You shouldn't point your A-Record to the IP of your app until you're ready to redirect traffic from your old host to Pagoda Box. You should also allow sufficient time after turning your TTL down for DNS caches to clear (48-72 hours).

Add SSL (Optional)

All apps on Pagoda Box have free access to Pagoda Box's piggy-back SSL at their Pagoda Box URL (, but once you point your custom domain to your app on Pagoda Box, you will need a to add your own SSL. How to do this is covered in the Adding SSL documentation.

Point Your DNS to Pagoda Box

Once your ready for your app on Pagoda Box to start handling traffic, simply change your DNS A-Record to point to the IP provided in your dashboard under Network > Inbound IP Addresses. If you've added a Dedicated Inbound IP Address, and/or have bound an SSL certificate to an IP, use those IPs.

If you waited the 48-72 hours for DNS caches to clear, downtime will be minimal as traffic is routed to your app on Pagoda Box.

That's it! You're Transitioned!

Once your custom domain is switched over, your app will start handling traffic and you're done!

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