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:

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:

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:

  1. Choose your hook point - e.g. first_thing
  2. Choose your hook type - e.g. command
  3. Set a target server-type for the hook - e.g. mysql
  4. If your target is not any then set the run_on to either single_server or all_servers.
  5. 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:

  1. 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.
  2. Paste in your (validated) YAML
  3. 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.

  1. Navigate back to Application Overview
  2. Click the Build / Deploy button
  3. 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?

Need help with deployments?
Contact Support
More Questions?
Join the Slack Channel