Login Try it Free

Understanding the Boxfile

Last Updated: Aug 13, 2013 12:59PM MDT

The Boxfile is at the heart of configuring your app for Pagoda Box. After reading this, you should know how to:

  •  Configure PHP for your app
  •  Create shared writable directories
  •  Mucho mucho more...
 

What's a 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 

Before explaining all the possible configurations, please note that our infrastructure uses Apache. We recognize and read .htaccess files where much of your app's configuration takes place.

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.

The Boxfile Structure

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 

/Boxfile

 Component Types and Numbers Are Not Arbitrary 

When defining a component type, you must include a number, even if there is only one of that component type. This number is not arbitrary—It is what ties a component in your Boxfile to a component in your app.

Boxfile Triggers

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 

If you have component Triggers in your Boxfile and delete those components through your app dashboard, they will be recreated on the next deploy unless you remove them from your Boxfile. On the flip-side, if you delete components from your Boxfile, they will not be removed from your app unless you remove them through the dashboard.

Global Config Options

Environment Variables 

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

 YAMLEnvironment Variables 

file name: /Boxfile

Web Component Config Options

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.

  Web Component Names in the Dashboard  

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

 YAMLCustom Web Component Name 

/Boxfile
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 

/Boxfile

 

 WARNING: 

Any directory specified here will no longer be tracked via git in the Pagoda repo.

These should be used sparingly. Only use these for upload content or possibly as a central cache store.

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 

/Boxfile
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 

/Boxfile
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 

/Boxfile

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 

/Boxfile
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 

/Boxfile
php_error_reporting 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Error Reporting 

/Boxfile
php_display_errors 

 YAMLPHP Display Errors 

/Boxfile
php_short_open_tag 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Short Open Tag 

/Boxfile
php_default_mimetype 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Default MIME Type 

/Boxfile
php_date_timezone 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Date Timezone 

/Boxfile
php_default_locale 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Default Locale 

/Boxfile
php_max_execution_time 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Max Execution Time 

/Boxfile
php_max_input_time 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Max Input Time 

/Boxfile
php_post_max_size 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Post Max Size 

/Boxfile
php_file_uploads 

See PHP.net Docs for definition & configuration options.

 YAMLPHP File Uploads 

/Boxfile
php_upload_max_filesize 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Upload Max File Size 

/Boxfile
php_max_file_uploads 

See PHP.net Docs for definition & configuration options.

 YAMLPHP Max File Uploads 

/Boxfile
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 

/Boxfile

Log Streams

Log streams are logs that are output into the Pagoda logger. They can be enabled or disabled in the Boxfile. While a log stream is disabled, the output of those logs will not be stored and will not be accessible if re-enabled. View the Log Managment guide for more information.

Log Streams in the Boxfile 

Enabables/disables log streams output to the Pagoda logger.

 YAMLLog Streams 

/Boxfile

Database Component Config Settings

The following are configuration options available for cloud database components.

 Automated Environment Variables 

Anytime you create a database, we automatically create Environment Variables for each of your database credentials.

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 

/Boxfile
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 

/Boxfile

Cache Component Config Settings

The following are configuration options available for cloud cache components.

 Automated Environment Variables 

Anytime you create a cache component, we automatically create Environment Variables for each of your cache credentials.

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 

/Boxfile
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 

/Boxfile

Worker Component Config Options

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 

/Boxfile

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 

/Boxfile
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 

/Boxfile
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.

If you have any suggestions or corrections for this guide, please submit a ticket.

Contact Us