Things to Know When Moving to Pagoda Box V2

Last Updated October 2014

Pagoda Box V2 is finally here with some very exciting updates. There have been a lot of changes, and there’s a few things existing Pagoda Box users need to know about. This doc walks through the major differences between the old and new Pagoda Box infrastructures. After reading it, you should be familiar with:

  • Getting your app ready for V2
  • The differences between the old and new Pagoda Box

We highly recommend reading through this entire doc.

Migrating Existing Apps

The underlying structure of Pagoda Box V2 is completely different from the original Pagoda Box. Because of this, app migrations are necessary. We have provided a migration tool in the v1 dashboard that will take care of most of the heavy lifting for you. This tool is documented in the Using Butler – Migrating from Pagoda Box v1 to v2 doc. You should also read through the Prepping Your App for a Smooth v2 Migration doc.

Manually migrating an app to the new infrastructure is, for the most part, a fairly simple process. The Manually Migrating Apps from Pagoda Box v1 to v2 doc covers the steps in detail.

If you feel the migration process is beyond what you're comfortable with, we are on hand to help. Feel free to contact Pagoda Support or join us in IRC.

"Components" Are Now "Services"

Individual pieces of your application (web1, web2, db1, cache1, etc.) were formerly known as "components." They are now known as "services." This is only a nomenclature change, but it’s used in both the new dashboard and documentation.

Tinker & Production Apps

There are now two kinds of apps on Pagoda Box — Tinker apps and Production apps. Tinker apps are free apps with limited functionality. Production apps are paid apps with access to all Pagoda Box functionality. For the deep dive into these two kinds of apps, read through the Tinker & Production Apps doc.

Changes to the Boxfile

The Boxfile is still the center of the Pagoda Box workflow. It houses your app's configuration and now provides more options and functionality. Below are highlights worth noting.

Existing Boxfiles Will Work on Pagoda V2

The new deployment engine is built to be backwards compatible and the majority of existing Boxfiles will work without issue. However there may be a few edge cases that will not. If you happen to be one of these edge cases, please contact Pagoda Support.

More Config Options in the Boxfile

Many more configurations options have been opened up in the Boxfile. We now give you the ability to modify config settings unique to each service type. The Boxfile introduction doc is the best place to start a deep dive into all of the available configuration options. Or you can checkout the Boxfile Quick Reference for a quick overview of everything that's available.

Using v2 Boxfile Configs

v2 Boxfile configs will work alongside v1 configs, but you may choose to update your Boxfile to use all of the v2 syntax. The Legacy Boxfile Translations doc shows exactly what legacy configs can to be updated and how they should be updated.

"type" Configs are Required to Create Data Services from the Boxfile

With the availability of other database types other than MySQL, you must now specify a "type" when creating data services (databases & caches) from the Boxfile. If no type is specified, the service will not be created.

PHP Version Declaration

Declaring your php_version is now done differently. You now only specify the major and minor versions (5.3, 5.4, etc.). Patch versions are decided by the stability config. For more details, view the PHP Settings in the Boxfile doc.

New Build Settings & Hooks

In V2, the way code is built during the deploy process has changed. Instead of building code for individual services, code is now built once, then deployed to all code services. In the Boxfile, you can configure the environment in which your code gets built as well as what command(s) to run to actually build your code. The following docs have more information:

Build Settings in the Boxfile
Build & Deploy Hooks

Repo Size Limit

On v2, repos have a hard size limit of 3.5GB.

Code services are not created until code is pushed to Pagoda Box. New code services are always created on cloud instances, which have 4GB of disk. Pagoda Box requires a 512MB disk buffer to allow room for binaries, possible logs, etc. If you have more the 3.5GB of code in your repo, that along with the required disk buffer will exceed the disk space available and your app's build will fail.

Service Topologies, Instance Sizes, & Tiers


All services on Pagoda Box now have a "topology." The topology defines a service's architecture and how it will scale. There are three available topologies: Single, Redundant, & Cluster. More information is available in the Service Topologies doc.

New Instance Sizes & Tiers

Instance sizes and available resources are now uniform across all service types. Webs, workers, databases, caches, and storage all start with 128MB RAM Cloud instances and can scale up to use Private Cloud and Bare Metal instances. The dedicated tiers are no longer limited to just databases. For more details about the differences between each of the resource tiers, read through the Cloud, Private Cloud, & Bare Metal Resources doc.

Changes to Code Deployment

There are very important changes to the code deployment workflow when using Pagoda Box. These changes may affect the way you currently manage and deploy code on Pagoda Box.

SFTP / Vintage Mode Has Been Removed

SFTP deploys are no longer available on Pagoda Box. Vintage Mode has been removed. Git is now the only supported method for deploying code. While the jump to Git can be intimidating, there’s only a handful of commands you really need to know to commit and push code to Pagoda Box. These are covered in our Git Basics doc.

Only the Master Branch is Deployed

When pushing code to Pagoda Box, only code on the “master” branch will be deployed. All other branches will be rejected. Repos must have a “master” branch in order to deploy on Pagoda V2.

If you’re working locally on a branch other than master, pushing your local branch to your Pagoda remote’s master branch is really simple:

Pushing a Local Branch to a Different Remote Branch Terminal

  $ git push [remote] [local_branch]:[remote_branch]
  $ git push pagoda staging:master

All Pushes to the Pagoda Box Auto-Deploy

All pushes to Pagoda Box now auto-deploy. The option to disable auto-deploys on push has been removed.

Important Changes to Session Storage

By default, sessions are stored locally on each instance. Anytime you deploy, sessions will be cleared. Or if using multiple instances, each instance will have a unique set of sessions, likely resulting in odd behavior for your visitors. More information is available in the PHP Session Handling doc. It is highly recommended that you use an alternative method for storing sessions, such as Redis. A simple solution for storing sessions in Redis is outlined in our Redis doc.

Existing Redis Session Save Paths Need to be Updated

Many users are already storing sessions in Redis using the method described in this blog post. This method is still recommended, however, the host and port of redis can no longer be assumed. To allow the php_session_save_path to work out of the box, you'll need to update your Boxfile to use the auto-generated CACHE1_HOST & CACHE1_PORT environment variables:

Updated php_session_save_path YAML

    php_session_save_path: "tcp://${CACHE1_HOST}:${CACHE1_PORT}"
    type: redis

Data Migrations are Offline

Whenever a data service is scaled or repaired on Pagoda Box, we provision an entirely new instance in parallel to your currently running instance, and transfer all of your existing data to the new instance. Previously, all data migrations were done live, leaving the database available during the migration process. However, this method was slow and prone to data loss.

With offline migrations, data transfers are much faster and data-integrity is preserved. The only downside is your database will be unavailable for as long as it takes to move data from your current instance to your new instance (which with our 1Gbit network backbone, shouldn't take too long).

The Data Migrations During Scaling & Repairs doc provides more details about data migrations.

Composer Deploy Hooks No Longer Necessary

Previously, in order to use Composer on Pagoda Box, you had to run it as a after_build hook. On Pagoda V2, we run the composer install command as a default part of a PHP service's build. It's run as the default build "exec" hook. If the default composer install build exec doesn't suit your needs, you can provide your own.

The Composer doc explains how Composer and other dependency managers work on Pagoda V2.

SSH Access to All Services

You now have the ability to enable SSH access on each of your app’s services. Once enabled, you’ll be able SSH directly into your code services and SSH port forward into your data services. It also allows to you SSH/SFTP into your network storage (writable storage). This provides great flexibility, but there are some things you should be aware of. The SSH Access doc covers what you need to know in detail. Below are some other benefits of this new access.

The Tunnel is No Longer Necessary to Manage Data

Previously on Pagoda Box, the only way to remotely manage data was through the use of the Pagoda CLI’s “Tunnel.” With the introduction of SSH Access, the tunnel is no longer necessary. You can now connect to your data services through SSH port forwarding and manage your data.

The Pagoda Tunnel is still available in the V2 CLI, but is simply an alternative method for creating a remote connection to your database.

Running Commands Directly on Your Instances

A long-requested feature has been the ability to run commands directly from the command line. SSH access to services makes this possible. Simply SSH into your webs/workers and run commands through the command line. Note, only certain executables are available to each service type. The Available Executables doc provides a list of executables available to each service type.

App SSH Keys & Private Submodules

All apps on Pagoda Box now have their own set of SSH keys. These keys allow apps to connect to external services through an SSH connection. They're also used to download private git submodules on deploy.

In the past, in order to use private git submodules, you would have to add "pagodabox" as a collobator on your git hosting service. Now, all you need to do is add your app's public SSH key to your user account on your git provider. More information is available in the App SSH Keys doc.

Important Changes to Writable Storage

Writable storage now requires a Network Storage service. On the old Pagoda Box, writable directories were stored on a centralized writable filesystem and connected to your app’s instances through network mounts. This is still the case in V2, except the writable filesystem is unique to your app. You must create a Network Storage service in order to house “network directories” (formerly known as shared_writable_dirs). This filesystem's resources aren’t shared with any other apps. It’s yours to manage and scale.

View the Network Storage doc for detailed information about how Network Storage and Network Directories work.

Current Writable Directory Boxfile Configs Are Backwards Compatible

Current “shared_writable_dirs” Boxfile configs will still work on V2. Our deployment engine will automatically create a network storage service to house the network directories.

The PHP flock() Function is Not Supported on Network Storage

With the new structure and implementation of Network Storage, the PHP flock() function is no longer supported. This function locks a file when while it is being written to, preventing other requests from writing to it at the same time. However, flock() does not use a true OS level file lock and will not work on NFS services.

Apps that will be greatly affected by this are Magento apps. Magento's Admin panel has a dependency on the flock() function that will affect how the app functions. Part of the deploy process modifies Magento's config files to mitigate the flock() dependency.

Changes to Cron Jobs

On the old Pagoda Box, cron jobs required a transaction in order to fire a job. On Pagoda V2, cron jobs are loaded directly into a instance's crontab during the deploy process. Now cron jobs simply run on the instance that recieved the updated crontab (only one instance per service). Because of this, all time restrictions have been removed from cron jobs. You can now run them as often as you'd like and as long as you'd like. The Cron Jobs doc has more information.

Self-Signed SSL Certs No Longer Supported

Self-signed SSL certificates are no longer supported on v2. In order to use SSL, you will either need to use the Pagoda Box piggyback SSL on your dev url or an SSL certificate signed by a verifited Certificate Authority.

Application Logs

Application logs are now available in your dashboard. The Pagoda CLI is no longer required to view logs, but does allow you to if you'd like to use it. The Log Management doc goes into more detail.

Transaction Queueing

On the old Pagoda Box, starting a transaction while another was running wouldn't work. In Pagoda V2, transactions will now queue if another transaction is running. Once the current transaction finishes, the next transaction in the queue will begin.

We Have Switched to SmartOS

Pagoda Box no longer uses a Linux-based operating system. We have switched to SmartOS. This change is fundamental to the new Pagoda Box infrastructure, giving us much more visibility and flexibility. It won’t affect the vast majority of apps, but any app using custom executables compiled for Linux and included in their repo will no longer be able to use those executables.

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