Adding a deploy hook
Overview
Deploy hooks are scripts that allow you to automate actions at various points during the deployment process for your applications. This allows you to customise your deployments by, for example, installing software packages or upgrading components.
We will be walking through a simple example in this tutorial. For more detailed examples please read the in-depth How-to Guide. For a full list of every available option please read our reference guide.
What you’ll need
Before you start, please check you have the following:
- A Cloud 66 Account — If you don’t already have one, sign up for a Cloud 66 account. You’ll get free unlimited access to all products for 4 weeks.
- An existing application set up in Cloud 66 — To make the most of this tutorial you need to have an app already set up in Cloud 66. Follow our Getting Started guide if you’re not sure how to do this.
Creating a deploy hook
To make use of deploy hooks, your application should have a file called deploy_hooks.yml.
For Rails/Rack applications this file should be present within a folder named .cloud66, which is in turn located in the root of your source code.
/.cloud66/deploy_hooks.yml
This file should be YAML formatted, and you can use a service like YAMLlint to validate it.
A deploy hook needs, at a minimum:
- a hook point - where in the deployment process the hook must be invoked
- a hook type - either a
command
or one of the twoscript
types - a target - which type(s) of servers will use this hook
- a hook field - the command or script being run (or invoked)
Note
If you choose a specific server type as your target (i.e. anything other than any
) then your run_on field will default to single_server
unless you explicitly set it to all_servers
. If you set your server_type to any
, then this field is ignored.
So, to write a deploy hook you must:
- Choose your hook point - e.g.
first_thing
- Choose your hook type - e.g.
command
- Set a target server-type for the hook - e.g.
mysql
- If your target is not
any
then set the run_on to eithersingle_server
orall_servers
. - Configure the hook fields you require
While this is the bare minimum required to write a functional deploy hook, there are extensive options available for customization. Please read our reference guide to understand all the possibilities.
Writing the YAML
The simplest kind of hook is the command
. This simply executes a command in the operating system as part of the deployment process.
We’re going to add the hook below to our demo application:
first_thing: # Hook point
- command: apt-get install nmap -y # Hook type
target: any # Hook fields
execute: true
This hook will install the nmap
package on our server during the deployment process. We’ve added the execute
hook field because we want the command to be executed during deployment. If you don’t add this field, the code you’re calling won’t be executed.
Important
When automating the installation of packages, remember to use the -y flag to answer yes to all prompts.
Adding the hook to your app
To add a hook to your app:
- Create (or, if it exists, open) a file named deploy_hooks.yml in a folder named .cloud66 in the root of your source code repo.
- Paste in your (validated) YAML
- Commit the file to your repo
Deploying and testing
Now that our hook is in place, we need to re-deploy our application to see it in action.
- Navigate back to Application Overview
- Click the Build / Deploy button
- Watch the deploy log and you will see the “first _thing” deploy hook being called as part of the process
(As always, we recommend testing your hooks in a non-production environment before using on your live application.)
The best way to check whether your change has been applied to your server is to access it directly using SSH. Cloud 66 Toolbelt is the quickest way to do this.
Once you are connected to your server, type nmap
into the terminal. If your deploy hook was set up correctly, you will see the usage / help text for the nmap utility. If not, Ubuntu will complain that nmap is not installed.
What’s next?
- Get to grips with some advanced examples of deploy hooks to set up the exact hooks your app needs.
- Use the detailed reference guide for deploy hooks to set up the exact hooks your app needs.
- Learn how to use Manifest files to customize the components of your application
- Learn how to add custom environment variables to your application
- Learn how to use CustomConfig - a powerful tool for configuring the components of your application.