Understanding the Environment

Last Updated October 2014

Pagoda Box is not a traditional hosting environment. It's structured in a way that allows you to manage and scale your entire application simply and easily. Understanding how best to use the provided tools requires a bit of a paradigm shift in how you manage and scale your application. This doc will walk you through what you need to know. After reading it, you should be familiar with:

  • The overall infrastructure of Pagoda Box
  • The different ways you can scale your applications
  • How to configure your app's environment
  • How Pagoda Box is the apple to every other hosts' oranges

Infrastructure Nomenclature

Before we jump into the nitty-gritty, it's important to know some of the Pagoda Box nomenclature. It's pretty basic and there's really only two terms you need to know: Service and Instance.


A service is a functional "chunk" of your application devoted to a specific service type or language. There are five main types of services: webs, databases, caches, workers, and network storage. An app consists of one or more services, each individually configurable and scalable.


There are two main classifications of services: Code Services & Data Services.

Code Services

Code services house and run your application code. These include webs and workers.

Data Services

Data services house your application's data. These include databases, caches, and network storage.


Services consist of one or more instances — individual virtual or bare metal machines running either source code or a given process type.


It may be easier to think of services as clusters of instances. For example, if a PHP web service is scaled to five instances, it consists of five completely separate servers, each running their own PHP processes, but working together as one. The more instances a web or worker service has, the more concurrent requests they're able to handle.

Most, but not all, service types can have multiple instances (scale horizontally), but multiple instances behave differently depending on the service type. In webs and workers, multiple instances increase the services' ability to handle concurrent requests. In data services, they provide failover in case of an instance failure. A service's ability to run multiple instnaces is determined by its type and topology.

Apps are Distributed Across Multiple Servers

The major difference between Pagoda Box and other hosts is that your app is not confined to a single physical server, but is spread across a network of servers. In fact, all pieces of your application, from individual web instances to databases, potentially reside on completely different servers.

Apps on Multiple Servers

Even though your app is distributed across multiple servers, it still functions as a single unit. Pagoda Box takes care of all the necessary networking, letting you leverage the power of a true cloud infrastructure and do what you do best—code.

Multi-Node Environment

As stated above, services are comprised of one or more instances or "nodes." Each is completely isolated and unaware of others, but all work together.

For code services, adding instances is the primary and most efficient means of scaling to meet the demands of traffic. For a detailed explanation of this and other scaling strategies, check out the How & When to Scale doc. Working in a multi-node environment may require a shift in how you typically manage your applications.

Read-Only Privileges

By default, application code on Pagoda Box is housed in a Read-Only environment. This is done for a couple of reasons:

  1. Application continuity across all instances

  2. Security

Application Continuity

Multi-node environments consist of multiple, individual virtual servers (instances) completely unaware of each other, but working together as one. Read-only privileges prevent the potential risk of instances writing themselves out of sync, giving users a different experience depending on the instance to which their request is routed. One request could create a session on one instance, but their next request is routed to another instance where their session doesn't exist. A read-only environment keeps this from happening.


Pagoda Box was built from the ground up with security in mind. A read-only environment is just one of the precautions taken to make sure that your app is safe. You can learn more in the Security section below.

Network Storage

Many times write-access is required. In these cases, you are able to specify Network Directories — writable directories stored in a single, writable filesystem shared between all of your application instances. View the Network Storage doc for more information.

SSH Management of Live Code & Data

Because your application consists of multiple virtual servers, SSH management of each is different than in a traditional, one server setup. You are able to enable SSH access on each of your app's services, but there are things to note about SSH'ing into services on Pagoda Box. These are covered in detail in the SSH Access doc.

No Auto Installs

Many popular frameworks use auto-install scripts. Because of read-only privileges, auto-installers typically do not work on Pagoda Box. The best thing to do is to run the auto-installer in a local environment, commit all of the generated files to your repo, then deploy your code to Pagoda Box.

As a general rule, apps shouldn't write directly to configuration files on the Pagoda Box. Not only does this lead to performance issues in a distributed environment, but having writable config files opens up a huge security risk. Always write config files locally, then deploy.

Apps Live Behind a Load-Balancer

Every app on Pagoda Box lives behind a custom-built, load-balancing router. The routing mesh routes all requests made to any app on Pagoda Box to the correct app. It knows where every service and instances is on the infrastructure and routes requests accordingly. Requests are load-balanced between instances so you don't have to worry about any one instance getting overwhelmed.

Because apps reside behind a routing mesh, you'll need to use different request headers to capture information from incoming requests. You can view the list in our Request Headers to Use doc.

Granular Scalability

Something that will help you wrap your ahead around the Pagoda Box infrastructure is to stop thinking about what kind or size of server you need for your application. Think on a more granular scale. Instead of building on one massive server with enough power to cover you in peak times (and sits relatively unused the rest of the time), you're able to scale to the needs of each individual service within your application. Stop thinking about what resources your app as a whole needs. Start thinking about what each service in your application needs.

Pagoda Box allows you to scale only when/if needed. You no longer have to overbuild your infrastructure to handle huge traffic spikes. You can quickly and easily scale your application up to handle a surge in traffic, then right back down when traffic subsides. No need to waste resources and money waiting for the next big rush to come.


All app configuration is handled in the Boxfile. The Boxfile is a YAML config file placed in the root of your code repo. On each deploy, it's used to build and configure your infrastructure based on the specified settings. For everything you need to know about the Boxfile, check out the Boxfile doc.

The benefit of storing your environment configuration in the repo is that it is versioned with your code. So if you push a new configuration that causes issues with your live app, rolling back to the previous infrastructure is as easy as clicking the "Undo Last Deploy" button in your Dashboard. The previous, functional infrastructure will be built based on the Boxfile stored in the previous commit.

Seamless Deployment & Scaling

Web & Worker Services

Whenever you deploy new code to your application on Pagoda Box, new web/worker instances are provisioned in parallel to your currently running infrastructure. Once the new instances are verified as up and running, requests are routed away from the old to the new. The switch is atomic, allowing you to push changes to your live application without visitors to your app ever knowing.

When scaling your web & worker services, new instances are provisioned in parallel to your currently running service. Once they are up and running, the new instances begin handling requests and immediately increase your app's ability to handle concurrent requests. When scaling down your number of instances, they're simply removed from the service cluster, all without affecting your visitors.

Data Services

Data services (databases, caches, and network storage) are not affected by code deploys unless directly modified by a deploy hook or enable"Rebuild on Deploy".

However scaling or repairing a data service does require the service to be taken offline temporarily. In this process, we provision an entirely new instance in parallel to the currently running instance. Once the new instance is verified as up and running, data is migrated from the old to the new. Once the data data migration is complete, requests are routed to the new instance and the old is shut down. More information is available in the Data Migrations During Scaling & Repears doc.

Extensions & Packages

The vast majority of modern development languages are built to be highly extensible allowing developers to build and use tools specific to their needs. Dependency managers such as Composer have become an every day part of the development workflow. Pagoda Box makes it extremely easy to use these. For more information, check out the Composer doc.

PHP Extensions

PHP handles much of its extensibility in the form of PHP extensions, each of which must be compiled for a specific version of PHP. PHP Hosting companies primarily make these available in two ways:

  1. Install every extension a developer could want or need, weighing your app down with stuff which, for the most part, you will never use.

  2. Give you a blank slate and let you install and configure extensions yourself. This is great for developers who love configuring servers, but for everyone else, it's just one more thing to eat away time.

On Pagoda Box, PHP extensions are prepackaged for you, but are not enabled or installed by default. This helps to keep your application as light as possible. You can specify what extensions you need in your Boxfile. On deploy, whatever extensions are specified will automatically be included in your PHP build, avoiding any unnecessary weight in your app.

Lists of available extensions can be found in the PHP Extensions doc. If there is an extension you need that isn't currently available, feel free to let us know.


Pagoda Box was built with security in mind. Our infrastructure security policy is broken into three levels of interaction:

Public Network

The Public Network is a trusted "ring" comprised of any touch point someone from the outside may have with Pagoda Box or your application. This includes our dashboard, API, SSH, CLI, service tunnel, as well as your application and your users.

The "ring" protects, but does not have direct access to our core compute cluster. Each input type, such as the dashboard or service tunnel, can only communicate through a "gatekeeper." The gatekeeper validates every operation with the Pagoda Box Kernel, a centralized command center. If the kernel rejects the authorization attempt, the gatekeeper will not allow the operation and the input will be closed.

Each input type has varied levels of authentication dependent on the potential harm it could inflict. If the gatekeeper fails for any reason, all access is restricted until the gatekeeper can be restored to proper function.

Internal Network

Once an operation has been allowed through the Public Network ring, the remainder of the operation is subject to the internal network policy. We don't simply restrict access; we build a virtual network for every hosted application. Communication within app services is completely encapsulated until it arrives at its destination. It is not possible to intercept communication or attempt to explicitly connect to an unknown endpoint. The routers will simply drop packets intended for destinations outside of the VLAN.

Hosted Operations (OS-Level)

Your application is at the core of Pagoda Box. It lives within a highly encapsulated virtual machine. Pagoda Box runs on a modified SmartOS distribution on top of a custom illumos kernel.

Our virtualization stack leverages illumos zones and in some instances, kvm emulation. We are confident in the security isolation and are not aware of, nor do we think there will be any techniques that can escape the level of isolation provided. In addition, we patch and update the servers on a regular basis to defer any zero-day exploits.

On top of our virtualization layer, it may be necessary for your enterprise security policy to ensure physical (non-virtual) barriers exist between your app and other hosted apps. To meet this requirement, you can leverage our bare metal resources. Bare metal services are actual, physical servers of which your are the only tenant.

We are constantly updating and improving our security policies. We are confident in our ability to keep your application safe and secure at all times. That said, you are still responsible for the security of your application. We cannot prevent exploits within your application code. It is your responsibility to ensure people are doing what they should be doing within the scope of your application. We can ensure that if your app is compromised, it will not affect our infrastructure or any other hosted apps. You are responsible for your own application and any potential exploits within it.

Optimized Performance

Pagoda Box is the result of years of enterprise consulting and large scale implementations. Our team provides the default configuration of every environment which is generally the ideal, performant configuration. Of course, you can override defaults from the Boxfile, but know that any change may result in a performance decrease. We hope you'll enjoy the performance gains simply by launching your existing app on Pagoda Box.

Version Control

Pagoda Box leverages the power of Git for version control and deployment. Git stores states of your code in "commits." Each commit can be deployed or rolled back at any time. If you push a change that introduces a bug into your application, rolling back to a previous commit is as easy as clicking "Undo Last Deploy" in your Dashboard. Also, because your apps environment configuration is stored inside your repo, you're able to version control your entire infrastructure on Pagoda Box.

SmartOS Server Operating System

Pagoda Box servers run on the Solaris-based SmartOS operating system. SmartOS is incredibly powerful OS designed and built for highly-concurrent, virtualized environments. As a user, you typically don't have to worry about this unless you're compiling custom tools for your application. If your app currently has custom executables compiled for Linux-based servers, you will need to recompile them to work with Solaris. Know that not all tools are compatible with Solaris and will not compile.

No Technical Support for Custom-Compiled Executables

If you include custom-compiled executables in your codebase, we cannot provide any technical support for those executables. If you are having trouble compiling code to work on Solaris-based servers, you will need to contact the creator of the executable.

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