Deploy Hooks allow you to "hook" into the Pagoda deploy process and execute scripts or commands. This can be extremely useful for tasks such as altering files for the production environment, database migrations, clearing cache, or anything else your developer brain can conjure up. After reading this guide, you should be familiar with:
- Deploy Process
- Types of Deploy Hooks
- Configuring Deploy Hooks in the Boxfile
Understanding the Deploy Process
There are three different types of deploy hooks available to use: after_build, before_deploy and after_deploy. Each takes place at a different stage of the deploy process. To truly grasp how and when to use deploy hooks, you need to understand how the deploy process works.
Types of Deploy Hooks
after_build hooks run during the code preparation phase of the deploy process. At this point, you have write access to your source code, so any direct modification of your source needs to be done using after_build hooks. While you do have write access to your source, you do not have access to your shared writable directories or your database(s). Once code preparation is complete, your source code will be packaged into a read-only, deployable package and distributed to newly provisioned instances.
before_deploy hooks run after your packaged code has been distributed to newly created instances. These instances run in parallel to your current app instances, but traffic has not been routed to them yet. You no longer have write access to your source, but you do have access to your shared writable directories and your database(s). before_deploy hooks are handy for things like database migrations and unit tests.
If any of your after_build or before_deploy hooks fail, the deploy transaction abort the transaction. You can find the errors by viewing the transaction log in your app dashboard or your terminal output if you deployed from your command line.
after_deploy hooks run after traffic has been routed to your new instances. They are handy for things like clearing your cache.
Keep in mind that any modifications deploy hooks make to files or data outside of your git repo (e.g. database, writable storage) cannot be rolled back. It would be wise to have backups before executing deploy hooks that affect this data.
Deploy Hook Configuration
Like most Pagoda Box configuration settings, Deploy Hooks are configured in your application's Boxfile. Each hook should be nested under the appropriate component. Only components that contain application code will process deploy hooks. Currently, that only includes web components, but in the future it will also include background workers.
When defining deploy hooks in your Boxfile, you simply need to define the path to the script you want to run. If your deploy hooks reference any scripts inside your codebase, they need to be referenced from your project root, as opposed to the document root defined in your Boxfile. In many cases they are the same, but that isn't always the case.
It's important NOT to include a forward slash at the beginning of your path. This could cause your deploy hook(s) to throw an error.
Checkout the full list of executables available by default on Pagoda Box. This list will grow as new features are added. Below is an example of how deploy hooks are declared in the Boxfile.