In addition to Configuration variables read by Aptible, Aptible also lets you configure your Apps through a .aptible.yml file.

​
Location

If you are using Dockerfile Deploy, this file must be named .aptible.yml and located at the root of your repository.

If you are using Direct Docker Image Deploy, it must be located at /.aptible/.aptible.yml in your Docker image. See Procfiles and .aptible.yml with Direct Docker Image Deploy for more information.

​
Structure

This file should be a yaml file containing any of the following configuration keys:

​
before_release

For now, this is an alias to before_deploy, but should be considered deprecated. If you’re still using this key, please update!

​
before_deploy

before_deploy should be set to a list, e.g.:

before_deploy:
  - command1
  - command2
If your Docker image has an ENTRYPOINT, Aptible will not use a shell to interpret your commands. Instead, the command is split according to shell rules, then simply passed to your Container’s ENTRYPOINT as a series of arguments. In this case, using the form sh -c 'command1 && command2' or making use of a single wrapper script is required. See How to define services for additional details.

The commands listed under before_deploy will run when you deploy your app, either via a git push (for Dockerfile Deploy) or using aptible deploy (for Direct Docker Image Deploy). However, they will not run when you execute aptible config:set, aptible restart, etc.

before_deploy commands are executed in an isolated ephemeral Container, before new Release Containers are launched. The commands are executed sequentially in the order that they are listed in the file.

If any of the before_deploy commands fail, Release Containers will not be launched and the operation will be rolled back.

This has several key implications:

  • Any side effects of your before_deploy commands (such as database migrations) are guaranteed to have been completed before new Containers are launched for your app.
  • Any changes made to the container filesystem by a before_deploy command (such as installing dependencies or pre-compiling assets) will not be reflected in the Release Containers. You should usually include such commands in your Dockerfile instead.

As such, before_deploy commands are ideal for use cases such as:

  • Automating database migrations
  • Notifying an error tracking system that a new release is being deployed.
There is a 30-minute timeout on before_deploy tasks. If you need to run something that takes longer, consider using Ephemeral SSH Sessions.

​
After Success/Failure Hooks

Aptible provides multiple hook points for you to run custom code when certain operations succeed or fail.

Like before_deploy, commands are executed in an isolated ephemeral Container. These commands are executed sequentially in the order that they are listed in the file.

Success hooks run after your Release Containers are launched and confirmed to be in good health. Failure hooks run if the operation needs to be rolled back.

Unlike before_deploy, command failures in these hooks do not result in the operation being rolled back.
There is a 30-minute timeout on all hooks.

The available hooks are:

  • after_deploy_success
  • after_restart_success
  • after_configure_success
  • after_scale_success
  • after_deploy_failure
  • after_restart_failure
  • after_configure_failure
  • after_scale_failure

As their names suggest, these hooks run during deploy, restart, configure, and scale operations.

In order to update your hooks, you must initiate a deploy with the new hooks added to your .aptible.yml.

Please note that due to their nature, Failure hooks are only updated after a successful deploy. This means, for example, that if you currently have an after_deploy_failure hook A, and are updating it to B, it will only take effect after the deploy operation completes. If the deploy operation were to fail, then the after_deploy_failure hook A would run, not B. In a similar vein, Failure hooks use your previous image to run commands, not the current image being deployed. As such, it would not have any new code available to it.