New Boxfile Options - Stop Configuration & Current Working Directory

New configuration options are now available for web and worker components in the boxfile.yml. These new options allow you to customize how your application's web and worker processes are stopped and let you define the current working directory for start and stop commands.

What is Nanobox?

Nanobox is a "micro-platform" that builds and runs your application anywhere. It builds and provisions local development environments as well as scalable production environments using settings defined in your boxfile.yml.

Learn More About Nanobox

Stop Configuration Options

The following options allow you to configure how your web and worker processes get shutdown:

web.site:
  # ...
  stop: stop-command
  stop_force: true
  stop_timeout: 30

stop

The stop config defines the command used to stop your web/worker process(es). This is only necessary for processes that require a graceful shutdown process. In most cases the default is sufficient, but in some, there may be a need to control how a process gets shut down. Use-cases include workers with long-running tasks and supporting services that require a graceful shutdown.

stop_force

The stop_force config tells Nanobox whether or not to force stop your web/worker process after the stop_timeout is reached. The default is false.

If true, the server will send a SIGKILL when the stop_timeout is reached. If false, the server will send a SIGTERM when the stop_timeout is reached.

stop_timeout

The stop_timeout config defines the how long (in seconds) Nanobox should wait for the stop command to complete.

Stop Configs with Multiple Start Commands

Many apps require multiple processes running at the same time and each may require their own graceful shutdown. This can be accomplished in the boxfile.yml by using key-value pairs and an array of hashes for your start/stop configs.

web.site:
  start:
    monitor: monitor-start-command
    server: server-start-command
    proxy: proxy-start-command
  stop:
    monitor: monitor-stop-command
    server: server-stop-command
    proxy: proxy-stop-command
  stop_timeout:
    monitor: 45
    server: 30
    proxy: 15
  stop_force:
    monitor: false
    server: true
    proxy: true    

Note: You don't need to include configs for every start/stop key unless you need non-default behavior.

Current Working Directory

The cwd option defines the current working directory in which your webs' and worker's start/stop commands run.

web.site:
  # ...
  cwd: dir-name

Up to this point, to run a start command inside of a subdirectory of a project, you had to include a cd directive in your start command.

# Example of the old way of doing things. Don't do this.
web.site:
  start: cd dir-name && start-command

However, the directory context shift didn't allow runit, Nanobox's process manager, to properly track the process. If the process died, runit couldn't restart it.

With cwd, you can define the context for start and stop commands and runit can properly track the process(es). Any app that requires start commands to run in a directory other than the project root should be using the cwd command.

Using cwd with Multiple Start Commands

Many apps require multiple processes running at the same time and each may require their own working directory. This can be accomplished in the boxfile.yml by using key-value pairs and an array of hashes for your start/cwd configs.

web.site:
  start:
    monitor: monitor-start-command
    server: server-start-command
    proxy: proxy-start-command
  cwd:
    monitor: monitor-dir
    server: server-dir
    proxy: proxy-dir    

Note: You don't need to include cwd configs for start commands that run in the project root.

Stop Configuration
Current Working Directory

Posted in Features, Updates