Introducing Pagoda Box – a PaaS just for PHP

By Aleksander Koko

In this article, we’ll take a look at Pagoda Box, another PaaS (Platform as a Service). If you have used other PaaS in previous projects, Pagoda Box is similar to Heroku. Pagoda Box is PHP only (for now) and has a well defined architecture to start developing with PHP. Everything in PB is a component. The database is a component, the webservers, workers, cron jobs and the caching. Having such an architecture doesn’t only give you ease in development but also a control over money usage. This post will be a quick overview of this platform. We will set up a framework and look at a list of pros and cons, comparing it to Heroku.

PagodaBox website screeshot

Quick overview

Lets have a look at the components that Pagoda Box offers.

The first and the most important component is the Web Component. This component holds all the code and runs it on each request. This is the entry point in the application. You can have up to 25 instances of Web Components. You can chose from 200MB up to 1GB of RAM for each. In total, you can have 25GB per application. One Web Component with 200MB is free.

The database component doesn’t need an introduction. The only database that you can use for now is the MySQL database. You can chose one of two flavors, Cloud MySQL and Private Cloud MySQL. Only the Cloud MySQL has a free basic plan with 10MB of RAM. It can be scaled up to 500MB for one instance and the Private Cloud MySQL goes up to 16 CPU Cores, 16 GB of RAM, and 300 GB of storage.

The Caching Component comes in Redis and Memcached flavors. Both provide a free basic plan of 10MB. Both of them have only the Cloud version – no Private Cloud.

Pagoda Box also offers Cron Job components, Shared Writable Components (with a 10MB free plan) and SSL.

Setting up the local environment

In this example, we will see how to deploy the Slim framework in Pagoda Box. To be more accurate, I have chosen Slim Skeleton as it requires directories with write permission.

The first thing I do when starting a new project is to get Homestead set up. This is not a Laravel project but is the box I prefer to use. If you’d rather use Homestead Improved, which is simpler and more multi-platform ready, see this quickstart. Otherwise, continue with the instructions below. If you aren’t familiar with Homestead already, please read their documentation. There is a good guide with more in depth information.

After configuring Homestead.yaml using homestead edit my configuration looks something like this:

ip: ""
memory: 2048
cpus: 1

authorize: ~/.ssh/

    - ~/.ssh/id_rsa

    - map: ~/projects/homestead/Code
      to: /home/vagrant/Code

    - map:
      to: /home/vagrant/Code/slim-skeleton/public

    - homestead

    - key: APP_ENV
      value: local

The next thing I do is edit the hosts file on the host machine. I added the with the IP:

Navigate to your project folder and then clone the Slim Skeleton. My project folder is ~/projects/homestead/Code.

git clone slim-skeleton

After that, execute homestead up. Navigate inside the box using ssh to install dependencies using composer.

homestead ssh
cd Code
cd slim-skeleton
composer install

Check the browser for You should see something like this if you did everything ok.

Slim Skeleton on Homestead

Deploy the first application

If you haven’t already created an account on Pagoda Box please create one first. Create a new application. You can choose to start from an existing project, from an existing repository or an empty repository. The project is stored locally so we will go with the third option. Give it a name and launch the application.

If this is the first time you created a project, you have to configure the SSH keys. In case you aren’t familiar with SSH keys , read this article from Github on generating keys.

Configure ssh keys on PagodaBox

Before executing the commands that Pagoda Box suggests, first make sure to remove the existing Git files from the slim-skeleton folder.

rm -rf .git
rm .gitignore

After removing git files execute these commands:

git init
git add .
git commit -m 'your commit message'
git remote add pagoda *your pagodabox git repository here*
git push pagoda --all

Pagodabox push terminal

This will init a Git repo in this project, add all files, commit the changes, add a remote repository (project repo in Pagoda Box) and push everything to the server. After executing these commands click the Continue to App Dashboard button. Check your application URL in the browser to see if everything went well. If you don’t know the URL, it should be something like Don’t worry if you get an output like this:

PagodaBox first push without Boxfile

The first reason for this is that the webserver doesn’t point to the bootstrap PHP script. The starter PHP file (bootstrap) is located under the public folder. The index.php inside that folder initiates everything, as is the case in most modern PHP apps. Even if we navigate to the public folder we should see some errors. That’s because logs/ and templates/cache aren’t writable. By default, everything is read-only. We have to tell the webserver where the init file is, and that the two folders should be writable.

If you have used other PaaS platforms in the past, you may have used some configuration files. On Pagoda Box the configuration file is the Boxfile. Using this file you can tell the platform what components you want in the application. Don’t forget that every component is configurable. For example, you may want to have 3 web components, 2 private MySQL databases, 2 writable directories, maybe Redis for caching. All this can be configured via Boxfile. When you push your code onto Pagoda Box, the platform looks for a Boxfile and if one is provided, it will build the environment using the configuration within.

When we first pushed the code without the Boxfile, the platform was building the project using the default Boxfile. Components can be also configured using the dashboard but it’s recommended to use Boxfiles. Let’s say you have different versions of your application, and you want to rollback to a previous one. The platform will also scale to the scale of the previous.

Create a Boxfile in the root of the project. In this example we want 1 web component, 1 MySQL database, 2 writable directories, 1 environment variable (APP_ENV: production). If you noticed, on Homestead I used an environment variable and on Pagoda I used that same environment variable, but the value was different. So if I use this environment variable the code will work without changes in both environments. My final Boxfile looks something like this:

    - logs
    - templates/cache
  document_root: public
    - mysql

  name: slim
  type: mysql

    - APP_ENV: production

Now push all changes.

git add .
git commit -m "Adding Boxfile"
git push pagoda --all

Search again for your project in the browser and you should see that everything is OK now. You now have a ready to go project.

Pros and Cons

Pagoda Box is easy to get started with. It was easier for me than with Heroku, but I must admit that it is a bit outdated and lacks a lot of new features. If you have noticed in the dashboard, they advertise the version of PHP 5.5 as a new version, when 5.6 has been out for a while. Their documentation is really good and helps you a lot. What I like the most is the analytics area and the ease of scaling. I can scale very easily if my app grows faster than I thought, but I can’t really compare to Heroku (as a leading PaaS platform) because Heroku offers a lot extensibility. I can choose different 3rd party services and use them right away. Also, Heroku has a better definition on architecture as the creator of the 12 factor-app. Pagoda Box is PHP focused, while on Heroku it is not as easy to get started with PHP. If you are new to PaaS with PHP, you should give PagodaBox a try – especially if you’re just looking for a place to quickly deploy your app on. PagodaBox makes for a perfect prototype and example host.


In this article we saw what Pagoda Box was, and how to get started developing locally for it using Homestead. We created a foundation app which is a good base to start your application on. But don’t stop here. The dashboard of PagodaBox has a lot of analytics tools. Experiment with the various components which you didn’t get to use throughout this article – if you don’t break things, you will never learn, and on PaaS, rarely does anything stay broken.

We want to hear from you. Would you consider Pagoda Box in your next project? Have you tried it yet? What do you think about it?


This article seems to refer to v1 of the Pagodabox service which is due to be discontinued any day now in favour of their new v2 service. V2 makes several changes to the free tier, so that your web components require you log in to wake them up as opposed to auto-waking on access, and the base component specs are slightly different (less memory, for example).

I had an app running for several years and found it to be very easy to set up and administer. On the downside, though, there were frequent outages where my site was unavailable. The problems are supposedly resolved with v2 of the service.


Indeed it is for V1. We'll see if we can rewrite to make it focus on V2 more.


Hi @fretburner . Thanks for the reply. I'm the author of this article. I will update to v2 asap. It seems they updated it these days and I wrote this article a couple of months ago. My mistake.


Any idea when this article will be updated for Pagodabox v2?



Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Get the latest in PHP, once a week, for free.