Worker Service Settings in the Boxfile

Last Updated February 2015

Workers allow you to run processes in the background without timeouts. They are generally used for heavy or long-running processes like mail, billing, image processing, etc., as well as some added config options specific to workers. This doc walks through configuration options available to workers in the Boxfile. The Boxfile is a yaml config file that houses all configuration related to your app’s deployment and infrastructure. After reading this doc, you will be familiar with:

  • Configuring workers in your Boxfile
  • What options are available to workers in the Boxfile

More information can also be found in the Workers Documentation.


Overview of Worker Boxfile Settings YAML

  worker1:
    type: php
    version: 5.4
    stability: production
    exec: 'php path/to/worker.php'
    
    # Deploy Hooks
    deploy_hook_timeout: 600
    before_deploy:
      - "php db-migrate.php"
    after_deploy:
      - "php clear-cache.php"
    
    # Network Storage
    network_dirs:
      storage1:
        - dirA
        - dirB
      storage2:
        - dirC
    
    # Cron Jobs
    cron:
     - "0 * * * *": "php hourly-task.php"
/Boxfile

Worker Service Config Options

exec

The exec is the command that will start your worker process.

exec YAML

  worker1:
    exec: "php workers/mail.php"
/Boxfile

You Must Declare Your Executable

In your worker exec command, the executable must be declared. This can be done in one of two ways:

  1. Include the executable at the beginning of your command.
    Example: "php path/to/script.php"

  2. Declare in it your script with a shebang.

Name

Adding a custom name to your worker service is great for quick reference in your app dashboard. It will NOT change the name of your app.

name YAML

  worker1:
    name: site
   
  worker2:
    name: blog
/Boxfile
Version

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

version YAML

  worker1:
    type: php
    version: 5.4
/Boxfile
Stability

The "stability" config allows you to specify which patch level of your service "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, applications will be updated automatically on deploy.

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. Pagoda Box will only provide support for infrastructure-compatibility issues related to these specific versions. No app-compatibility support will be provided.

stability YAML

  worker1:
    type: php
    version: 5.4
    stability: production
/Boxfile
Network Directories

These directories are read/write accessible to all your worker instances. These directories are mounted at runtime, and should not be created at the same location as a directory containing source code in your repo. Filepaths should be relative to the root of your repo.

In order to use network_dirs, you must have one or more storage services to store them on. In your Boxfile config, specify which storage service the directories should be stored on. If no storage service is specified, we assume storage1.

For more details, view the Network Storage Documentation.

network_dirs YAML

  worker1:
    network_dirs:
      storage1:
        - path/to/directoryA
        - path/to/directoryB
      storage2:
        - path/to/directoryC
/Boxfile

Contents of Network Directories are Obscured by Network Mounts

On deploy, network directories are replaced with network mounts, which connect instances to your network storage service(s). These mounts obscure anything committed to your repo inside of those directories. If there are files inside network directories in your repo, your app will not be able to access them unless you manually upload them into your network storage service.

Nonpersistent Writable Directories

These directories are read/write accessible and stored in each instance's local filesystem. These directories are mounted at runtime, and should not be created at the same location as a directory containing source code in your repo. Filepaths should be relative to the root of your repo.

For more details, view the Nonpersistent Writable Directories doc.

nonpersistent_writable_dirs YAML

  worker1:
    nonpersistent_writable_dirs:
      - path/to/dirA
      - path/to/dirB
/Boxfile
Cron Jobs

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 Jobs Documentation for more details.

cron YAML

  worker1:
    cron:
      - "0 0 * * *": "rm -rf app/cache/*"
      - "*/3 */2 1-3 2,6,7 2": "echo 'im a little teapot'"
/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 Documentation.

before_deploy, after_deploy YAML

  worker1:
    deploy_hook_timeout: 600
    before_deploy:
      - "scripts/migrate_db.php"
    after_deploy:
      - "scripts/clear_cache.sh"
/Boxfile

Language & Service Specific Settings

Each language available in worker services has its own unique Boxfile configuration options. There are also 3rd party services with configuration options available in the Boxfile. The following docs outline each:

PHP Settings

View the available PHP settings in the PHP Settings in the Boxfile doc.

New Relic Settings

New Relic is a 3rd Party service that provides deep analytics related to your application's performance. Available New Relic configuration settings are coverd in the New Relic doc.

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