Understanding the Boxfile

The Basics

Pagoda Box is an app deployment platform. Since the focus of the platform is your app, and not the services that support the platform, all configuration related to your app’s deployment is contained in a single file called "Boxfile" (the capital "B" is important & no extension), located at the base of your git repo. In short, the Boxfile specifies how Pagoda Box should be configured for your source code. It's intended to be re-used whenever possible, especially when using frameworks for multiple projects. When a Boxfile is not present, we load a default Boxfile which works for most apps.

 Pagoda Box PHP apps run on Apache 

General Tips

1. The Boxfile must be valid yaml markup. You can brush up on your yaml here: yaml.org/start.html or check your syntax here: yamllint.com.

2. It is only necessary to use a Boxfile when the defaults are insufficient.

3. Place the Boxfile at the base of your repo.

4. Your Boxfile must be named "Boxfile" or it will not be recognized.

5. You only need to specify the difference between the default configuration and your specific configuration. That means, if only one setting needs to be changed, create a Boxfile with only that one setting. No need to go overboard. Note: This is on a per string basis. For example, if you're app has a database and you need to add php extensions other than the mysql extension, you must include the mysql extenstion in your extension string.

6. Since your app is tracked via git, so is your Boxfile. With each new deploy (including rollbacks), your Boxfile configuration will be loaded and matched to the contents of your Boxfile at that commit point.

Your app is made up of components. Simply put, a component is a piece of your app's infrastructure tasked with a specific function. Currently there are three types of components: Web, Database, and Cache Components. There will be more in the future.

Web Components

A web component houses and runs your app's source code using Apache. The Boxfile allows you to define a custom PHP build specific to your web component's needs. In the future, you will be able have multiple web components in a single app, all running on unique PHP configurations.

Database Components

A database component houses a database. You are currently able to run multiple database components in a single app.

Cache Components

A cache component like memcache, allows storing of data in RAM.

Components in the Boxfile

Configuration is done on a per component basis in the Boxfile. The available configurable options differs for each component type.

 YAMLSample Boxfile with Explanatory Comments 

 Component Types and Numbers Are Not Arbitrary 

One nice feature of the Boxfile is the ability it gives you to launch components on deploy. On each deploy, we check all components defined in the your Boxfile against existing components in your app. If a component in your Boxfile does not exist in your app, it will automatically be created. This allows you to deploy databases and other components when launching a new app.

 Heads-Up on Boxfile Triggers 

Environment Variables 

In addition to the Dashboard, you can also create Environment Variables in your Boxfile.

 YAMLEnvironment Variables 

The following section covers all of the available config options for web components.

name 

Adding a custom name to your web component will NOT change the name of your app. This is for quick reference in your app dashboard. In the future, you will be able to add multiple web components, so naming each web component will come in handy.

You can see how web component names appear in your app dashbaord

 YAMLCustom Web Component Name 

shared_writable_dirs 

These directories are read / write accessible to all your app clones. They are typically used for caching, logging, content uploaded via your app, etc. These directories are mounted at runtime, and should not be created at the same location as a directory containing source code in your repo.

 YAMLShared Writable Directories 

 WARNING: 

document_root 

The root of your executable app source. For instance, if you like to house your app in /app for security or organizational purposes, you can specify that here. All further configurations will be relative to this directory. Default is the root of your project.

 YAMLDocument Root 

Cron 

Cron is a time-based job scheduler that enables you to schedule jobs (commands) to run periodically at certain times or dates. See the Cron Guide for more details.

 YAMLCron Job 

Deploy Hooks 

Deploy Hooks are powerful tools that allow you to "hook" into the Pagoda deploy process and execute scripts or commands. Each type of hook takes place during a specific stage of the deployment process. For more details, see the Deploy Hooks Guide.

 YAMLDeploy Hooks 

PHP Config Options

The follow configurations options specify your PHP build.

php_version 

The version of php to load into your secure executable container. The following versions are available on Pagoda Box:

5.2.17
5.3.5
5.3.6
5.3.8
5.3.10
5.3.23 (Default)
5.4.14

 YAMLPHP Version 

php_extensions 

By default, your php executable is extremely slim, and only contains the core interpreter. All additional extensions will be loaded when we spawn your executable processes. You can specify them simply as a comma delimited list.

You can view the available extensions available for your version of php via the following links:

PHP 5.2.17
PHP 5.3.5, 5.3.6, 5.3.8 & 5.3.10
PHP 5.3.23
PHP 5.4.14

 YAMLPHP Extensions 

php_error_reporting 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Error Reporting 

php_display_errors 

 YAMLPHP Display Errors 

php_short_open_tag 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Short Open Tag 

php_default_mimetype 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Default MIME Type 

php_date_timezone 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Date Timezone 

php_default_locale 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Default Locale 

php_max_execution_time 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Max Execution Time 

php_max_input_time 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Max Input Time 

php_post_max_size 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Post Max Size 

php_file_uploads 

See PHP.net Docs for definition & configuration options.

 YAMLPHP File Uploads 

php_upload_max_filesize 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Upload Max File Size 

php_max_file_uploads 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Max File Uploads 

apache_log_level 

Sets the minimum importance for a message to be logged (the "level" of the message). See LogLevel Apache Docs for available levels.

 YAMLApache Log Level 

The following are configuration options available for cloud database components.

 Automated Environment Variables 

name 

Creating a custom name for your database component will do two things:

1. Act as a quick reference in your app control room. If you have multiple database components, custom names will come in handy.

2. Set your Database Name credential.

If you do not define a custom name, Pagoda Box will generate a database name for you.

 YAMLDatabase Name 

type 

This one is fairly self-explanatory. What type of database you need completely depends on your app. MySQL is the default database type.

 YAMLDatabase Type 

The following are configuration options available for cloud cache components.

 Automated Environment Variables 

name 

Creating a custom name for your cache component will do two things:

1. Act as a quick reference in your app control room. If you have multiple cache components, custom names will come in handy.

2. Set your cache Name credential.

If you do not define a custom name, Pagoda Box will generate a cache name for you.

 YAMLCache Name 

type 

This one is fairly self-explanatory. What type of cache you need completely depends on your app. Memcached is the default cache type, but Redis is also available.

 YAMLCache Type 

Workers can be configured using the majority of the web config options, but there are some added config options specific to workers. Check out the Background Workers Guide for details and a simple worker use-case.The majority of workers will only need a simple configuration, but there are also some advanced options:

Simple Config

All that's needed to get a worker up and running is the command to start your worker.

exec 

The command that will start your worker process.

 YAMLexec 

Advanced Config

The advanced configuration allows you to customize how Pagoda Box starts and stops your workers. A new worker is started with each deploy after which the previous worker is stopped and decommissioned.

start 

This allows you to set a specific start behavior for your worker instances. The deploy will pause and stream all output from your worker until one of two conditions are met:

1. The output contains your "ready" string.
2. The timeout limit is reached.

There are two config options for start: ready and timeout.

 YAMLStart Config 

ready

The string your worker will output when it is ready to handle requests.

timeout

The length of time (in seconds) the deploy stream will stay open waiting for your "ready" string. When the timeout is reached, we assume a successful start and continue the deploy process. The default timeout is 2 seconds.

stop 

This allows you to set a specific stop behavior for your worker instances. In many cases, workers are assigned tasks that can not simply be stopped without a proper "shutdown" process. The stop config allows you to define that shutdown process and gracefully stop your worker instances, if necessary. There are three config options for stop: signal, timeout, and exec.

 YAMLStop Config 

signal

Workers are stopped by sending the process a UNIX kill signal. The default kill signal is "SIGQUIT". Here you can specify any valid POSIX kill signal. It is not required that your workers shutdown immediately upon receiving the kill signal.

timeout

The length of time (in seconds) worker instances are allowed to run after they've received the kill signal. The default timeout is 60 seconds. NOTE: Instances are decommissioned at the moment the process stops, regardless of the timeout setting.

exec

This command is executed instead of sending your worker a kill signal. It is useful if your worker cannot gracefully trap a UNIX kill signal. One use case might be to trigger a script that would set a value in a database. The worker could recognize the value before the next iteration and exit.