oneoff

Manage running one-off tasks for NodeJS applications on Cloud Foundry.

Cloud Foundry doesn't provide access to the host machine or bound services running your application. This makes running manual configuration tasks (initialize this database, upgrade this table schema, etc.) during deployment a challenge...

There are a number of ways to ~~hack~~ work around this but they rely on manual deployment steps, e.g. temporarily deploy a single instance of your application with a custom start command. Yuck.

Using oneoff, you define your tasks as code which are automatically run during the normal deployment.

oneoff provides the following features...

• ensure tasks are completed before application startup
• coordinating app instances to ensure at-most once task execution
• automagically discovering tasks from the task directory
• dependency ordering, ensure task a completes before task b starts
• parallel task execution
• ignore completed tasks in future deployments

No more snowflake ops.

install

usage

Once onceoff has been installed, you will need to write your tasks and then hook the module into your application startup.

defining tasks

Tasks are NodeJS modules that implement the following interface:

name, done & task are mandatory attributes, order is optional and defaults to zero.

done will execute callback with two arguments, the error parameter (or null) and the boolean value with the results of the test which determines whether the task has been executed previously.

task will execute callback with one argument, the error parameter or null, when the task has finished.

For example, creating a new task to set up the database schema for our application would follow the outline below.

These modules will be loaded using require() at runtime and executed according to the following ordering rules.

1. Tasks with the same order value are executed concurrently.
2. Tasks with order value N will only be executed when all tasks with order value < N have finished.
3. Tasks without an explicitly order property defined are assigned the default order value (0).

All tasks must live under the same parent directory. Files without the ".js" postfix or with the . prefix will be ignored.

Any NPM packages defined in your package.json will be available to your tasks.

application startup

Set the oneoff command to run before your application starts, e.g. using prestart or start NPM scripts.

By default, oneoff will search for tasks under the ./lib/tasks directory. This location can be modified using the --tasks ./path/to/tasks command line argument.

If the oneoff command has been correctly registered into application startup, the following log entries should appear:

Errors from the tasks will cause the command to exit with a failure status code and force the application startup to fail.

limitations

Cloud Foundry default application startup time is limited to sixty seconds. If task execution pushes the startup time over this threshold, the health check will restart the application.

This value can be increased to a maximum of three minutes using the timeout property in the application manifest.

tests