Intro

We’ve recently started to investigate cloud hosting platforms, such as PHPFog and Pagodabox, as an alternative to our current Linode hosting. While Linode is a fantastic host, each project requires that we spend an hour or so to provision our host for staging and production environments, and on top of that, the benefits of cloud scalability and managed hosting has really started to make sense for us internally. Over the past few weeks we’ve seen a few different mentions of setting up EE on one of these “cloud environments”, and we wanted to share our experience doing just that. In this article we will describe the process of setting up an EE site on Pagodabox and also discuss some of the tricky parts we ran into. Also, as a disclaimer, this is not an all-inclusive look at cloud hosting. It is merely an explanation of the steps we took to setup EE on one of these platforms. Furthermore, this tutorial assumes you have an understanding of terminology like Git, SSH, Public Keys, Staging Environments, etc. If you do not and get stuck on something, don’t be scared. Some quick Googling should to the trick.

Before we get started, we should first explain our typical multi-environment setup. Typically when building EE sites, we will have a local version of the EE project running on our individual machines where we develop the site locally. Each site is version controlled using Git, and when we get to the point where we want to show the site to the client, we create a staging instance of site on our remote staging host. From then on, we deploy all code changes to the staging environment using Capistrano. All production environments are setup in a similar fashion with deployments being handled through Capistrano. To configure EE to the different environments we utilize Leevi Grahams Bootstrap Config file, to handle different settings for different environments. It should be noted that using some sort of dynamic, environment-specific configuration settings should be used when utilizing a cloud hosting platform. This article will assume you currently are using one, and know how to configure EE settings to fit multiple environments.

Why Pagodabox?

We’ve taken a look at two cloud hosting solutions PHPFog and Pagodabox. While both hosts seem like good solutions we ended up going with Pagodabox because it gives you the ability to create DB tunnels and manage your hosted DB using local tools such as Sequel Pro. Also because it allows you to SSH into your shared writeable directories, making backup and migration much easier. Next, we’ll walk you through the process of getting a an EE instance up and running on Pagodabox. Like many dev/design shops, in many cases we are setting up hosting for our clients, so this article points out a few places where the process is not so straight forward.

Creating Your Account and Application

The first step is creating an account with Pagoda Box. Head over to http://pagodabox.com and do just that. After confirming your account and logging in for the first time, you get taken to this screen where you can create a new application.

After clicking New Application you’re taken to a screen where you can pick how you want to start your application. For our purposes select Empty Repo, give your project a name and click Launch Application.

Choosing a Deployment Method

After some quick processing you are taken to a new screen where you select your deployment method. This is one of the places we ran into some issues. To preface the issue, the specific hiccup we ran into was related to a use-case where we were setting up a Pagodabox application for a non-technical client, using their own account credentials. If you are not worried about this use-case and understand how to setup Git, feel free to disregard this issue and go ahead and setup your Git repository as the site directs.

As for our issue, Pagodabox only allows a single developer’s Public Key to be used once across their entire platform. If you associate your Public Key with a Pagodabox account, you will not be able to use that same Public Key on another account. This issue is tricky because if you create a new account for your client, then take steps to setup the application on your own machine, when you select to deploy via Git it will prompt you to enter your Public Key, however after submission it will alert you that the Public Key has already been associated to an account and can’t be used again. This is a pretty big issue because it hypothetically means the account owner needs to understand how to create Public Keys and initialize Git repositories in order to setup an application.

There are two recommended workarounds for this situation.

1. When logged into your clients account and creating a new application, when it asks you to choose your deployment method choose SFTP. After your application has been created and you are taken to your application dashboard, go to the Admin section and then change the deployment method back to Git. Lastly, add yourself as a collaborator to the application. This will give you access to push and pull from the application’s Git repository.

2. Instead of creating the application while logged in under your clients PagodaBox account, create the application as if it were your own, on your account. Setup the application normally using Git and after you have created the application, you can add your client as a collaborator to the application. After they have been added as a collaborator, there is the option to transfer ownership of the application to their account.

Continuing with our setup process, at this point you should either have created an application using Git as a deploy method or using SFTP. If you did so using SFTP, follow the steps to switch the account to use Git deployment.

Configuring Our Local Environment

On our local machines there are a few key components we need to add to the codebase.

Boxfile

The Boxfile is a yaml based configuration file you can use to run tasks and specify various environment parameters for your PagodaBox application. To learn more about the Box file, checkout this article: Understanding the Boxfile, which goes into much more detail. There are a plethora of configurations you are able to set in the Boxfile, but the two biggest in our case are: shared_writeable_dirs and php_extensions

Before we talk about these in more detail, here is the Boxfile used in our EE app. Go ahead and add a copy to your application, which you will configure for your application. The Boxfile should be located in the root of your application’s codebase and should be named “Boxfile” with no extension.

It should be noted that a Pagoda Box project does not actually need a Boxfile to run, and each Pagoda Box application has default settings applied to it when there is no Boxfile present in the repository.

PHP Extensions

For an EE project, we need to specify inside the Boxfile that we want to turn on the mysql extension and the GD image library extension.

Shared Writeable Directories

The other configuration of our Boxfile is the shared_writeable_dirs setting. This setting specifies writeable directories the application should have access to. For example: file upload and cache directories. One thing to note is that when these directories are specified in the Boxfile, and pushed to the PagodaBox environment, PagodaBox does some behind the scenes work to remove all contents of the specified directories and symlink them to a location that is not included in the Git repository. Because of this removal and symlinking, the directories get emptied, which means you will have to upload any files and folders located in them via SSH or SFTP. Inside your Boxfile change the shared_writeable_dirs settings to match your application’s requirements.

Pagoda Gem

Pagodabox provides a Ruby Gem to interact with your account and applications. This gem can help you setup applications, create db tunnels, and deploy and rollback your application. Before moving on, take a look at this article and install the gem for yourself.

For our application, the main thing we use the gem for is to connect to our remote DB. After installing the gem open terminal and navigate into your local version of the codebase. From there enter the command

$ pagoda tunnel -c db1

This should start the process of initiating a DB tunnel, which will allow you to connect to the DB with a tool such as Sequel Pro.

Export and Import DB

The next step is to export your local DB and import it into your PagodaBox hosted DB. Go ahead…

Push Codebase Live

Lastly we want to push the code live. Commit anything you have not yet and run:

$ git push pagoda

After the push has executed, a few other commands get run and terminal should report the status of the deployment.

Upload Shared Writeable Directory Content

With the codebase pushed live, including our recently created Boxfile, the last step is moving files contained within your Shared Writeable Directories to your environment. To do this, first you will need to enable SSH connection from the Pagodabox application control panel. Navigate to the Admin page of your account and click the box next to where it says Enable SSH access to your writeable directories.

After enabling writeable directories, you can SSH into your PB account or connect via SFTP.

Inside you will see a few folders, we are looking for the shared directory. Inside the shared directory you’ll see the folders you specified as writeable inside your Boxfile, however their contents are empty. Go ahead and upload the files you need to from your local version of the site. Also, make sure you set the permissions of these folders correctly. I know EE requires that file upload directories be 777, so make sure you have them set accordingly here.

Test Out Your Site

With the final steps completed, you should now be ready to test out your application. Fire up the url provided by Pagodabox and see if everything is working correctly.

Conclusion

Almighty, clear as mud, right? This process took us about a week’s worth of playing around with Pagodabox to figure out, so hopefully this helps push you in the right direction. There is a chance we missed something along the way, so feel free to reach out in the comments with any comments or questions and we’ll do the best we can help.

Comments