Build Settings in the Boxfile

Last Updated October 2014

When apps are deployed, a "build instance" is provisioned in which your code is built and prepped for deploy. Build settings allow you to configure your build instance as well as how your code gets built. After this reading this doc, you should be familiar with:

  • Configuring the build instance for your app
  • Customizing the build process of your app
  • Getting your build on and loving it

Overview of Build Boxfile Settings YAML

  build:
    type: php
    version: 5.4
    stability: production
    
    # Build Hooks
    build_hook_timeout: 600
    before_exec:
      - "mv pagoda/composer.json composer.json"
    exec:
      - "composer install --no-interaction --prefer-source"
    after_exec:
      - "curl -O js/jquery.js http://code.jquery.com/jquery-2.1.1.min.js"
    
    # Libary / Package / Dependency Configs
    lib_dir: vendor
    reuse_libs: true
/Boxfile

Build Configs Only Apply to Build Instances

Build configs only apply during the build phase of the deploy process. The type, version, and stability set here will not apply to your app's web/worker instances.

Build Instance Config Options

Version

The "version" config specifies which version of php to use. Only the major and minor version should be specified. The patch level is determined by the "stability" config.

version YAML

  build:
    type: php
    version: 5.4
/Boxfile
Stability

The "stability" config allows you to specify which patch level of your build "version" you'd like to use. There are three stability options:

  • alpha

  • beta

  • production

Pagoda Box assigns the patch levels to each stability setting. When the patch levels are updated, build instances will be updated automatically.

Alpha & Beta Versions

Alpha and beta versions are for bleeding edge developers who want nothing but the latest releases of languages. Please note however, Pagoda Box does not guarantee the compatibility of these versions with the Pagoda Box infrafstructure or your app. These are "builds-in-progress," and using them is done at your own risk.

stability YAML

  build:
    type: php
    version: 5.4
    stability: production
/Boxfile

Build Hooks

Build hooks allow you to customize how your code is built and prepped for deploy. These are also covered in the Build & Deploy Hooks doc. The Available Executables doc lists the executables avaialable to each build type.

Before Exec

before_exec hooks run just after your code has been cloned into a build instance and git submodules have been loaded. These can be used to prepare your code for its build process.

before_exec YAML

  build:
    before_exec:
      - "mv pagoda/config config"
/Boxfile
Exec

The exec allows you to run custom build scripts for your app. These are typically used to load dependencies into your code base. The Default build exec provided by Pagoda Box runs Composer. This is covered in the Composer Dependency Management doc.

exec YAML

  build:
    exec:
      - "composer install"
/Boxfile
After Exec

after_exec hooks run after all dependecies and submodules are loaded into your app and just before your code is deployed to read-only instances.

after_exec YAML

  build:
    after_exec:
      - "curl -o js/jquery.js http://code.jquery.com/jquery-2.1.1.min.js"
/Boxfile
Build Hook Timeout

This allows you to define a timeout (in seconds) for you app's build hooks. If a build hook times out, it will exit and the build will abort.

build_hook_timeout YAML

  # Default setting
  build:
    build_hook_timeout: 600
/Boxfile

Library & Package Management

The following settings allow you to control libraries, packages, & dependencies that are loaded during the build process. These are also covered in the Composer Dependency Management doc.

Library Directory

The library directory config (lib_dir tells Pagoda Box where your dependency manager stores its dependencies. After the dependencies have been downloaded, the lib_dir is packaged into a “library archive” which is used on subsequent deploys.

Note: It is possible to have multiple library directories. All directory paths should be relative to the root of your repo.

lib_dir YAML

  build:
    lib_dir: vendor
   
    # For Multiple lib_dirs
    lib_dir:
      - vendor
      - packages
/Boxfile
Reuse Libs

The reuse_libs config allows you to specify whether or not you want a library archive to be stored and reused on subsequent deploys. If set to false, libraries and packages will be downloaded on all deploys, increasing deploy times.

reuse_libs YAML

  build:
    reuse_libs: true
/Boxfile

Checkout the Boxfile Quick Reference to see a full build config.

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