Legacy Boxfile Translations

Last Updated October 2014

Pagoda Box v2 introduces many new Boxfile configuration options and structure, extending what’s possible through the Boxfile. While the new Boxfile parser is built to be backwards compatible with Legacy Boxfile, you may want to convert your entire Boxfile to the new format. This doc identifies what legacy configs can be updated and how they should be updated.


Legacy Boxfile Translation Table

Quick Notes

  • Many of the legacy Boxfile configs have not changed in the v2 Boxfile and do not need to be updated. This doc only covers those that have changed and can be updated if using v2 configs.

Legacy Config v2 Config
  web1:
    php_version: 5.4.14
  web1:
    version: 5.4
    stability: production
  web1:
    document_root: public
  web1:
    httpd_document_root: public
  web1:
    index_list:
      - index.html
      - index.php
  web1:
    httpd_index_list:
      - index.html
      - index.php
          
  web1:
    apache_log_level: warn
  web1:
    httpd_log_level: warn
  web1:
    apache_access_log: false
    apache_error_log: true
  web1:
    httpd_access_log: false
    httpd_error_log: true
  web1:
    shared_writable_dirs:
      - path/to/dirA
          - path/to/dirB
  web1:
    network_dirs:
      - path/to/dirA
      - path/to/dirB
  web1:
    after_build: "php script.php"
  build:
    after_exec: "php script.php"
  db1:
    name: dbname
  database1:
    name: dbname
    type: mysql
  db1:
    type: mysql
  database1:
    type: mysql
  worker1:
    exec: "php mail.php"
    start:
      ready: "ready for jobs"
      timeout: 2
    stop:
      signal: SIGQUIT
      timeout: 60
      exec: "stop-mail.php"
  worker1:
    type: php
    exec: "php mail.php"

  # Worker start & stop configs
  # no longer available

The Differences Explained

PHP Version Declarations

Declaring your PHP version is now done differently. Each service has a "version" config. You now only specify the major and minor versions (5.3, 5.4, etc.). Patch versions are decided by the stability config. For more details, view the PHP Settings in the Boxfile doc.

"Shared Writable Directories" Are Now "Network Directories"

Legacy “Shared Writable Directories” (shared_writable_dirs) are now known as “Network Directories” (network_dirs). This name change was made primarily to indicate the architecture of the service rather than the function. While network directories are writable, their purpose is to provide a centralized filesystem accessible by all your app’s instances over a network connection.

You now also have the ability to create multiple storage services within an application and specify what network_dirs are stored on each service. More information is available in the Network Storage doc.

Apache Configs Now Prepended with httpd

This change was another made primarily for clarity. Apache is the name of the organization that manages many different projects. httpd is the name of the web server built and maintained by Apache and used in PHP and Static web services on Pagoda Box. But the two are used synonymously.

In some legacy configs, Apache/httpd was assumed and not indicated in the config name. For example, “document_root.” The document root defines the web accessible root. This is actually in httpd setting and not a PHP setting. In v2, Apache/httpd configs are available to more than just PHP, so they had to be separated out.

"after_build" Hooks Are Now "after_exec" Build Hooks

In Pagoda Box v2, the build process for code services has been re-architected. You now have the ability to configure the build process and the environment in which your code is built/prepped for deploy. These configurations are handled in the new “build” node available in the v2 Boxfile. All legacy after_build hooks were run during the build phase of the deploy process and have therefore been moved into the build config. They have also been renamed to “after_exec”.

More information is provided in the following docs:
Build & Deploy Hooks
Build Settings in the Boxfile

"db1" Should Now Be "database1"

This change was made for the sake of consistancy. Databases were the only components (now called “services”) with an abbreviated ID. In v2 Boxfiles, database is no longer abbreviated in service IDs. Note this change also affects the names of auto-generated environment variables.

Worker Start & Stop Configs No Longer Available

Worker “start” and “stop” configs have been removed from the v2 Boxfile. They were rarely used in legacy Boxfiles and, when used, were often unnecessary.

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