Boxfile Quick Reference

Last Updated February 2015

The Boxfile gives you granular control over each of the services within your app. It is a yaml config file that houses all configuration related to your app’s services. This doc is meant to be a quick reference to allow you to quickly see what options are avialble in the Boxfile.


Global Settings

Global settings are options that aren't specific to any particular service. They apply to your app as a whole.

Global Options YAML

  global:          
    # Environment Variables
    env:
      - "ENVIRONMENT": "PRODUCTION"
/Boxfile

More details about the available global options can be found in these docs:

Environment Variables

Build

The build section of the Boxfile allows you to configure the environment in which your code is built and prepped for deploy as well as how your code gets prepped. These configs only apply during the build phase of the deploy process. The type, version, and stability set here will not apply to your web/worker instances.

Build Settings in the Boxfile 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

More details about the available build options can be found in these docs:

Build Settings in the Boxfile
Build & Deploy Hooks
Composer

PHP

The following Boxfile config options are available to PHP webs & workers.

PHP Settings in the Boxfil YAML

  web1:
    type: php
    version: 5.4
    stability: production
   
    # php.ini Settings
    php_extensions:
      - json
      - mbstring
      - pdo
      - session
      - xml
    php_zend_extensions:
      - ioncube_loader
    php_expose_php: "Off"
    php_error_reporting: 30719
    php_display_errors: "1"
    php_disable_functions:
      - exec
      - shell_exec
      - system
    php_max_children: 20
    php_max_requests: 128
    php_max_execution_time: 30
    php_max_input_time: 60
    php_post_max_size: "8M"
    php_max_input_vars: 1000
    php_file_uploads: "1"
    php_upload_max_filesize: "2M"
    php_max_file_uploads: 20
    php_opcode_mem_percentage: 50
    php_allow_url_fopen: "On"
    php_short_open_tag: "1"
    php_default_mimetype: "text/html"
    php_date_timezone: "US/central"
    php_default_locale: "en_US"
    php_geoip_custom_directory: "/data/app/GeoIP/"
    php_browscap: "/data/app/browscap.ini"
    php_register_globals: "0"
    php_iconv_internal_encoding: "UTF-8"
    php_register_argc_argv: "Off"
    php_zlib_output_compression: "Off"
    php_mail_add_x_header: "On"
    php_session_save_handler: "files"
    php_session_save_path: "/tmp/pagodabox/sessions"
    php_session_length: "3600"
    php_session_autostart: "0"
   
    # Deploy Hooks
    deploy_hook_timeout: 600
    before_deploy:
      - "php artisan migrate"
    before_deploy_all:
      - "php scripts/clear_cache.php"
    after_deploy:
      - "php checksum.php"
    after_deploy_all:
      - "php scripts/prime_cache.php"
   
    # Network Storage
    network_dirs:
      storage1:
        - dirA
        - dirB
      storage2:
        - dirC

    # Nonpersistent Writable Directories
    nonpersistent_writable_dirs:
      - path/to/dirA
      - path/to/dirB
   
    # Cron Jobs
    cron:
     - "0 * * * *": "php hourly-task.php"
/Boxfile

More details about the options available to PHP services can be found in these docs:

PHP Settings in the Boxfile
PHP Extensions
Build & Deploy Hooks
Network Storage
Nonpersistent Writable Directories
Cron Jobs

Also note that all Apache settings are available to PHP web services.

Apache

The following Apache config options are available in the Boxfile. Apache is only used in PHP & Static web services.

Apache Settings in the Boxfile YAML

  web1:
    httpd_document_root: public
    httpd_index_list:
      - index.html
    httpd_version: 2.2.23
    httpd_php_interpreter: mod_php
    httpd_modules:
      - include
      - env
      - mime_magic
      - rewrite
      - fastcgi
    httpd_log_level: warn
    httpd_timeout: 30
    httpd_server_limit: 128
    httpd_max_clients: 128
    httpd_static_expire: 86400
    httpd_server_admin: 'email@domain.com'
    httpd_xsendfilepaths:
      - /var/www/public/files
      - /var/www/other
/Boxfile

More details about the available Apache config options can be found in the Apache Settings in the Boxfile doc.

Workers

Workers can use all the config options avilable to it's type, the language the worker is running. However, all workers require an exec, the command to start your worker process.

Worker Settings in the Boxfile YAML

  worker1:
    version: 5.4
    stability: production
    exec: 'php path/to/worker.php'
   
    # Deploy Hooks
    deploy_hook_timeout: 600
    before_deploy:
      - "bash scripts/deploy-prep.sh"
    before_deploy_all:
      - "php scripts/clear_cache.php"
    after_deploy:
      - "bash scripts/deploy-cleanup.sh"
    after_deploy_all:
      - "php scripts/prime_cache.php"
   
    # Network Storage
    network_dirs:
      storage1:
        - dirA
        - dirB
      storage2:
        - dirC

    # Nonpersistent Writable Directories
    nonpersistent_writable_dirs:
      - path/to/dirA
      - path/to/dirB
   
    # Cron Jobs
    cron:
     - "0 * * * *": "php hourly-task.php"
   
    # Any other config options available to your worker type
/Boxfile

More details about the options available to Worker services can be found in these docs:

Workers
PHP Settings in the Boxfile
Build & Deploy Hooks
Network Storage
Cron Jobs

MySQL, MariaDB, & Percona

The following Boxfile config options are available to MySQL, MariaDB, & Percona databases.

MySQL, MariaDB, & Percona Settings in the Boxfile YAML

  database1:
    type: mysql
    version: 5.5
    stability: production
    topology: redundant
    mysql_plugins:
      - federated
      - audit_log
    mysql_event_scheduler: 'Off'
    mysql_max_connections: 1024
    mysql_thread_stack: '256K'
    mysql_myisam_recover: 'DEFAULT'
    mysql_max_allowed_packet:  '16M'
    mysql_max_join_size: 9223372036854775807
    mysql_table_open_cache: 64
    mysql_query_cache_limit: '1M'
    mysql_allow_suspicious_udfs: 'Off'
    mysql_ansi: 'Off'
    mysql_audit_log: 'On'
    mysql_ft_max_word_len: 84
    mysql_ft_min_word_len: 4
    mysql_ft_query_expansion_limit: 20
    mysql_ft_stopword_file: ' '
/Boxfile

More details about the available MySQL config options can be found in the following docs:

MySQL, MariaDB, & Percona Settings in the Boxfile
Service Topologies

PostgreSQL

The following Boxfile config options are available to PostgreSQL databases.

PostgreSQL Settings in the Boxfile YAML

  database1:
    type: postgresql
    version: 9.4
    stability: beta
    topology: single
/Boxfile

More details about the available PostgreSQL config options can be found in the following docs:

PostgreSQL Settings in the Boxfile
Service Topologies

MongoDB

The following Boxfile config options are available to MongoDB databases.

MongoDB Settings in the Boxfile YAML

  database1:
    type: mongodb
    version: 2.6
    stability: production
    topology: single
    mongodb_diaglog: 0
    mongodb_objcheck: true
    mongodb_log_verbosity: 'v'
    mongodb_directoryperdb: true
    mongodb_logappend: true
    mongodb_nojournal: false
    mongodb_noscripting: false
/Boxfile

More details about the available MongoDB config options can be found in the following docs:

MongoDB Settings in the Boxfile
Service Topologies

Redis

The following Boxfile config options are available to Redis caches.

Redis Settings in the Boxfile YAML

  cache1:
    type: redis
    version: 2.8
    stability: production
    topology: single
    redis_tcp_keepalive: 60
    redis_databases: 16
    redis_stop_writes_on_bgsave_error: 'yes'
    redis_slave_serve_stale_data: 'yes'
    redis_slave_read_only: 'yes'
    redis_repl_ping_slave_period: 10
    redis_repl_timeout: 60
    redis_repl_disable_tcp_nodelay: 'no'
    redis_max_clients: 1024
    redis_maxmemory_policy: 'volatile-lru'
    redis_maxmemory_samples: 3
    redis_appendonly: 'no'
    redis_appendfsync: 'everysec'
    redis_no_appendfsync_on_rewrite: 'no'
    redis_auto_aof_rewrite_percentage: 100
    redis_auto_aof_rewrite_min_size: '64m'
    redis_lua_time_limit: 5000
    redis_slowlog_log_slower_than: 0
    redis_slowlog_max_len: 128
    redis_hash_max_ziplist_entries: 512
    redis_hash_max_ziplist_value: 64
    redis_list_max_ziplist_entries: 512
    redis_list_max_ziplist_value: 64
    redis_set_max_intset_entries: 512
    redis_zset_max_ziplist_entries: 12
    redis_zset_max_ziplist_value: 64
    redis_activerehashing: 'yes'
    redis_hz: 10
    redis_aof_rewrite_incremental_fsync: 'yes'
/Boxfile

More details about the available Redis config options can be found in the following docs:

Redis Settings in the Boxfile doc
Service Topologies

Memcached

The following Boxfile config options are available to Memcached caches.

Memcached Settings in the Boxfile YAML

  cache1:
    type: memcached
    version: 1.4
    stability: production
    topology: single
    memcached_return_error_on_memory_exhausted: false
    memcached_max_connections: 1024
    memcached_chunk_size_growth_factor: 1.25
    memcached_minimum_allocated_space: 48
    memcached_maximum_requests_per_event: 20
    memcached_disable_cas: false
    memcached_max_backlog: 1024
    memcached_binding_protocol: 'auto'
/Boxfile

More details about the available Memcached config options can be found in the following docs:

Memcached Settings in the Boxfile
Service Topologies

Network Storage

Network Storage services house network directories. On the actual network storage service, all you really need to do is specify the service type.

Network Storage Settings in the Boxfile YAML

  storage1:
    type: nfs
    topology: single
/Boxfile

More details about how network storage is configured and functions can be found in the following docs:

Network Storage
Service Topologies

Log Management

The following Boxfile configs allow you to configure logs for you application.

Log Settings in the Boxfile YAML

  web1:
    # App Logs to Show in Log Stream
    log_watch:
      custom[log]: 'path/to/my-custom.log'
      app[log]: 'path/to/my-app.log'

    # Apache & PHP Log Toggles
    httpd_access_log: false
    httpd_error_log: true
    php_error_log: true
    php_fpm_log: true
/Boxfile

More details about log management are available in the Log Management doc.

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