The Boxfile is responsible for much of the granular control and streamlined workflow available on Pagoda Box. It is a yaml config file that houses all configuration related to your app’s deployment and infrastructure and allows you to custom-configure your app's environment to your project's specific needs. This doc is an overview that introduces key concepts and what options are available. After reading it, you will be familiar with:
- Configuring your app's infrastructure
- What options are available in the Boxfile
- How awesome it is configure your entire infrastructure in a single file
What is a Boxfile?
All configuration related to your app’s deployment and infrastructure is contained in a single yaml file named "Boxfile" that, when needed, should be included as part of your project's code repo. Boxfiles are intended to be re-used whenever possible, especially when using frameworks for multiple projects.
Important Things to Know About the Boxfile
Your Boxfile must be named "Boxfile" (capital B and no file extension) or it will not be recognized by our deployment engine.
The Boxfile must be placed at the root of your project repo.
Services are created from the Boxfile, but removing them from the Boxfile will not destroy them. Services can only be destroyed from the dashboard or the Pagoda CLI.
It is only necessary to use a Boxfile when the defaults are insufficient.
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 your app has a database and you need to add php extensions other than the mysql extension, you must include the mysql extension in your extension string.
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.
Sample Boxfile YAML
build: type: php version: 5.4 stability: production exec: - "composer install --no-interaction --prefer-source" lib_dir: vendor reuse_libs: true web1: name: site type: php version: 5.4 stability: production network_dirs: storage1: - usr/uploads httpd_document_root: app php_extensions: - mysql - gd - eaccelerator database1: name: posts type: mysql topology: redundant storage1: name: filestore type: nfs cache1: name: sessions type: redis worker1: name: image_processor type: php exec: 'php workers/image_processor.php'
The Boxfile Structure
Your app is made up of services. Simply put, a service is a piece of your app's infrastructure tasked with a specific function. Currently there are five types of services: Web, Database, Cache, Storage and Worker services. Each of these services are configured in the Boxfile.
Each service has a service id. For example: web1, web2, database1, database2, storage1, cache1, worker1, etc.
Service IDs Are Not Arbitrary
Service IDs consist of the service type and a number (web1, web2, database1, database2, ect.). This number is not arbitrary — It is what ties a service in your Boxfile to a service in your app and are necessary for each and every service.
All configuration is unique to a service ID. It's important to understand that every service is completely separate from the others. Settings specified for web1 will not apply to web2. Anything specified under a service ID will only apply to that specific service.
Boxfile Structure YAML
web1: #<------------------------- Service ID name: site #| version: 5.4 #|----- Service Settings stability: production #| database1: #<-------------------------- Service ID name: my-db #| type: mysql #|----- Service Settings version: 5.5 #| stability: production #|
Yaml is very picky about indentation. Indentation is what is used to define the relationship structure of information in your Boxfile. Nested "nodes" belong to a parent "node" as illustrated below.
Tabs Are Not Valid YAML
It's important to note that tabs are not valid yaml. All indendation should be done using double spaces.
The Boxfile is an Infrastructure "Seed" File
In many ways, the Boxfile acts as a "seed" file for your infrastructure. It gives you the ability to launch services and add things like environment variables and cron jobs on deploy, simply by including them in the Boxfile. On each deploy, we check all services and settings defined in the your Boxfile against those already existing in your app. If a service or setting in your Boxfile does not already exist, it will automatically be created. This allows you to deploy databases and other services when launching a new app.
Heads-Up on Creating Things from the Boxfile
If you have services or settings in your Boxfile that you delete or modify 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 services from your Boxfile, they will not be removed from your app unless you remove them through the dashboard.
The Boxfile.install is an optional Boxfile that allows you to apply configuration options to only the very first deploy of app. All of the same config options available in the Boxfile are available in the Boxfile.install. Both a Boxfile and a Boxfile.install can exist in the same repo. Boxfile.installs are primarily used to create Quickstarts.
How the Boxfile.install Works
Settings specified in the Boxfile.install only apply to the very first deploy of an app. During the deploy process, the Boxfile and Boxfile.install are merged and parsed as a single Boxfile. If a specific setting is specified in both, the one in the Boxfile.install will take priority.
On all subsequent deploys, the Boxfile.install is completely ignored.
There are many use cases for Boxfile.installs, but here are just a few:
Sample Data Imports
Many times, when creating a quickstart, you'll want/need to import sample data into your database to provide users with a fully functional app out of the box. However, you don't want to run a data import on all deploys because it would wipe out any changes to the data. Running the import in a deploy hook in your Boxfile.install will make sure the import only runs on the very first deploy.
Many popular CMSs include an auto-installer to help users get up and running. These auto-installers typically don't work well in Pagoda Box's read-only environment. Some users have used Boxfile.installs, deploy hooks, and a little scripting magic to do the work these auto-installers would typically do.
Global Config Options
Global config options are applied to your app as a whole.
Environment variables can be used for obscuring sensitive information, simplifying multi-environment management, or any other way you can think of to use Environment Variables in your app. They can be generated from your Boxfile.
global: env: - KEY: value - ENV: production
For more information on Environment Variables, check out the Environment Variables documentation.
Build Config Options
Whenever you deploy your application, a "build instance" is provisioned for the sole purpose of building your code and preparing it for deploy. Code is only built once, then deployed to all code service instances (webs & workers). These settings allow you to configure the environment in which your code is prepped for deploy. They also allow you to customize how your code gets built.
Build config options are covered in detail in the Build Settings in the Boxfile doc.
Service Specific Configurations
Each service has specific configuration options available to it. Below are docs that outline these options:
Web Service Settings
You can see the available web service settings in the Web Service Settings in the Boxfile doc.
Database Service Settings
You can see the available database service settings in the Database Service Settings in the Boxfile doc.
Network Storage Service Settings
You can see the available storage service settings in the Storage Service Settings in the Boxfile doc.
Cache Service Settings
You can see the available cache service settings in the Cache Service Settings in the Boxfile doc.
Worker Service Settings
You can see the available worker service settings in the Worker Service Settings in the Boxfile doc.
Table of Contents
If you have any questions, suggestions, or corrections, let us know.