Worker Service Settings in the Boxfile
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"
Worker Service Config Options
The exec is the command that will start your worker process.
worker1: exec: "php workers/mail.php"
You Must Declare Your Executable
In your worker exec command, the executable must be declared. This can be done in one of two ways:
Include the executable at the beginning of your command.
Declare in it your script with a shebang.
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.
worker1: name: site worker2: name: blog
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.
worker1: type: php version: 5.4
The "stability" config allows you to specify which patch level of your service "version" you'd like to use. There are three stability options:
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.
worker1: type: php version: 5.4 stability: production
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
For more details, view the Network Storage Documentation.
worker1: network_dirs: storage1: - path/to/directoryA - path/to/directoryB storage2: - path/to/directoryC
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.
worker1: nonpersistent_writable_dirs: - path/to/dirA - path/to/dirB
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.
worker1: cron: - "0 0 * * *": "rm -rf app/cache/*" - "*/3 */2 1-3 2,6,7 2": "echo 'im a little teapot'"
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"
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:
View the available PHP settings in the PHP Settings in the Boxfile doc.
New Relic Settings
Table of Contents
- You Must Declare Your Executable
- Alpha & Beta Versions
- Network Directories
- Contents of Network Directories are Obscured by Network Mounts
- Nonpersistent Writable Directories
- Cron Jobs
- Deploy Hooks
If you have any questions, suggestions, or corrections, let us know.