What are deploy hooks?

Deploy hooks are scripts that allow you to take action at various points during the deployment process. This helps you customize the deployment of your application to meet your particular needs.

Hook points

The deployment process is divided into a number of steps, and hook points allow you to intervene at various points during this process.

Hook fields

There are four types of deploy hooks, and the fields available (and required) vary by type:

1. Snippets: use pre-existing scripts to install common packages. These snippets are open source, and are created by Cloud 66 or third parties.
2. Commands: run your own commands.
3. Existing Scripts: use your own existing scripts for more comprehensive procedures (Rails/Node stacks only)
4. Inline Scripts: use your own inline scripts for more comprehensive procedures

Field	Description
HOOK TYPE: Snippets
snippet	Snippet to be used - runs in /tmp/deploy_hooks by default
target	Target server(s), with accepted values any, rails, mysql, postgresql, mongodb, redis, sinatra, padrino, custom Note: Please make sure you read the run_on part, if your target is not any
execute (false)	Set to true for the code to be executed during deployment
executable (false)	Set to true for the code to be made executable on the target. Defaults to true if execute is true
apply_during (all)	Specify when you want the deploy hook action to take place. Accepted values are build_only, deploy_only or all. The build step occurs the first time a stack is deployed, and will re-occur until the stack has been successfully deployed at least once. After this subsequent deployments are deploy steps
env_vars	Hash of values that will be set when running this specific deploy hook. Only applies to deploy hooks that have execute = true If the stack already contains this env var it will be overridden with the value specified here.
halt_on_error (true)	Specify whether the execution should continue or halt in the event of an error
run_on (single server)	If you have multiple servers in the same group (eg. scaled-up Rails servers), you can specify whether you want the deploy hook action to occur just once or once against each server in that group. Valid values are: single_server or all_servers. If you've specified target: any above, this will apply to all servers
run_as (server user)	If you execute a file on your target server, specify which user you would like the file to be executed as Note: you can't specify both this and sudo
sudo (false)	If you are executing the file on your target server, specify whether you want that execution to be sudo-ed? Note: you can't specify both this and run_as

Field	Description
HOOK TYPE: Commands
command	Command to be used - run in /tmp/deploy_hooks by default
target	Target server(s), with accepted values any, rails, docker, mysql, postgresql, mongodb, redis, sinatra, padrino, custom Note: Please make sure you read the run_on part, if your target is not any
execute (true)	Set to true for the code to be executed during deployment
executable (false)	Set to true for the code to be made executable on the target. Defaults to true if execute is true
apply_during (all)	Specify when you want the deploy hook action to take place. Accepted values are build_only, deploy_only or all. The build step occurs the first time a stack is deployed, and will re-occur until the stack has been successfully deployed at least once. After this subsequent deployments are deploy steps
env_vars	Hash of values that will be set when running this specific deploy hook. Only applies to deploy hooks that have execute = true If the stack already contains this env var it will be overridden with the value specified here.
halt_on_error (true)	Specify whether the execution should continue or halt in the event of an error
run_on (single server)	If you have multiple servers in the same group (eg. scaled-up Rails servers), you can specify whether you want the deploy hook action to occur just once or once against each server in that group. Valid values are: single_server or all_servers. If you've specified target: any above, this will apply to all servers
run_as (server user)	If you execute a file on your target server, specify which user you would like the file to be executed as Note: you can't specify both this and sudo
sudo (false)	If you are executing the file on your target server, specify whether you want that execution to be sudo-ed? Note: you can't specify both this and run_as

Field	Description
HOOK TYPE: Existing Scripts (Rails/Node stacks only)
source	This specifies the source location of your deploy hook file within your repository
target	Target server(s), with accepted values any, rails, mysql, postgresql, mongodb, redis, sinatra, padrino, custom Note: Please make sure you read the run_on part, if your target is not any
env_vars	Hash of values that will be set when running this specific deploy hook. Only applies to deploy hooks that have execute = true If the stack already contains this env var it will be overridden with the value specified here.
execute (false)	Set to true for the code to be executed during deployment
executable (false)	Set to true for the snippet to be made executable on the target. Defaults to true if execute is true
destination	The destination path on your target server. You can also specify environment variables in your destination field; <%= ENV['STACK_PATH'] %> for example
apply_during (all)	Specify when you want the deploy hook action to take place. Accepted values are build_only, deploy_only or all. The build step occurs the first time a stack is deployed, and will re-occur until the stack has been successfully deployed at least once. After this subsequent deployments are deploy steps
halt_on_error (true)	Specify whether the execution should continue or halt in the event of an error
run_on (single server)	If you have multiple servers in the same group (eg. scaled-up Rails servers), you can specify whether you want the deploy hook action to occur just once or once against each server in that group. Valid values are: single_server or all_servers. If you've specified target: any above, this will apply to all servers
run_as (server user)	If you execute a file on your target server, specify which user you would like the file to be executed as Note: you can't specify both this and sudo
sudo (false)	If you are executing the file on your target server, specify whether you want that execution to be sudo-ed? Note: you can't specify both this and run_as
parse (true)	Specifies whether the file being transferred should be parsed for environment variables. Using this you can embed <%= ENV['ENV_VAR'] %> for example in your source file, and have it resolved during the deploy hook action
owner (your server user)	Ownership permissions for the file (and destination folder) on the target server. An example could be user:group

Field	Description
HOOK TYPE: Inline Scripts
source	This specifies the source location of your deploy hook file within your repository
target	Target server(s), with accepted values any, rails, mysql, postgresql, mongodb, redis, sinatra, padrino, custom Note: Please make sure you read the run_on part, if your target is not any
env_vars	Hash of values that will be set when running this specific deploy hook. Only applies to deploy hooks that have execute = true If the stack already contains this env var it will be overridden with the value specified here.
execute (false)	Set to true for the code to be executed during deployment
executable (false)	Set to true for the snippet to be made executable on the target. Defaults to true if execute is true
destination	The destination path on your target server. You can also specify environment variables in your destination field; <%= ENV['STACK_PATH'] %> for example
apply_during (all)	Specify when you want the deploy hook action to take place. Accepted values are build_only, deploy_only or all. The build step occurs the first time a stack is deployed, and will re-occur until the stack has been successfully deployed at least once. After this subsequent deployments are deploy steps
halt_on_error (true)	Specify whether the execution should continue or halt in the event of an error
run_on (single server)	If you have multiple servers in the same group (eg. scaled-up Rails servers), you can specify whether you want the deploy hook action to occur just once or once against each server in that group. Valid values are: single_server or all_servers. If you've specified target: any above, this will apply to all servers
run_as (server user)	If you execute a file on your target server, specify which user you would like the file to be executed as Note: you can't specify both this and sudo
sudo (false)	If you are executing the file on your target server, specify whether you want that execution to be sudo-ed? Note: you can't specify both this and run_as
parse (true)	Specifies whether the file being transferred should be parsed for environment variables. Using this you can embed <%= ENV['ENV_VAR'] %> for example in your source file, and have it resolved during the deploy hook action
owner (your server user)	Ownership permissions for the file (and destination folder) on the target server. An example could be user:group

How to use deploy hooks

To make use of deploy hooks, your stack should have a file called deploy_hooks.yml.

For Rails/Rack stacks 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

For Docker stacks this file should be pushed into CustomConfig git Repository of the stack. This repository will be created after the stack is analysed, so you can push your deploy hooks before deployment started.

This file should be YAML formatted, and you can use a service like YAMLlint to validate it.

Creating a deploy hook from scratch consists of a number of steps:

1. Choose your environment - eg. example production, development, staging and so on.
2. Choose your hook point - eg. first_thing, after_rails and so on.
3. Choose your deploy hook type - eg. snippet, command or script.
4. Select any additional hook fields you require

Automating deploy hooks can sometimes be tricky. To avoid issues, it’s good practice to run each of your commands manually to see that they complete successfully.

If a specific command doesn’t show any output, you can use the echo $? command after issuing your command to see its exit code. If it returns a zero, your command was successful, whereas a one means it has failed.

Use a snippet deploy hook

Below is a bare-bone example of using a snippet with the required fields - it will execute the Cloud 66 Node snippet as the first thing on all production servers.

production: # Environment
    first_thing: # Hook point
      - snippet: cloud66/rails # Hook type
        target: any # Hook fields
        execute: true

You can also run several snippets at the same hook point like follows:

production: # Environment
    first_thing: # Hook point
      - snippet: cloud66/rails # Hook type
        target: any # Hook fields
        execute: true
      - snippet: cloud66/bower
        target: any
        execute: true

See the available hook points and fields for more ways to customize this.

Use a command deploy hook

The hook example below can be used to install anything from packages to fonts on your server, and you can nest different hooks for the same hook point like follows:

production: # Environment
    first_thing: # Hook point
      - command: apt-get install curl -y # Hook type
        target: any # Hook fields
        execute: true
      - command: apt-get install ncdu -y # Hook type
        target: any # Hook fields
        execute: true

Important

When automating the installation of packages, remember to use the -y flag to answer yes to all prompts.

The example below can be used to run custom rake tasks during server build. If you need to run it more than once, consider using the rake task add-in.

production: # Environment
    last_thing: # Hook point
      - command: cd $STACK_PATH && bundle exec rake dev:setup # Hook type
        target: rails # Hook fields ↓
        run_on: single_server
        apply_during: build_only

This will run our rake task on one Rails server and only during the initial build. We run this as a last_thing hook because if we ran it earlier the application wouldn’t exist on the server and be usable.

Use an existing script deploy hook (Rails/Node stacks only)

The hook below will copy a file from your repository to your tmp folder and execute it during build.

production: # Environment
    after_rails: # Hook point
      - source: /.cloud66/script.sh # Hook type
        destination: /tmp/script.sh
        target: rails # Hook fields ↓
        execute: true
        apply_during: build_only

Use an inline script deploy hook

The hook below will create an arbitrary log file in /tmp

first_thing: # Hook point
 - inline: |

     #!/usr/bin/env bash
     echo "script called!" >> /tmp/inline_script.log
   target: any
   execute: true
   apply_during: all
   owner: root:root

Other examples

The example shows how to use the env_vars parameter.

before_nginx:
   snippet: cloud66/download
   target: rails
   execute: true
   apply_during: build_only
   run_on: all_servers
   env_vars:
     SOURCE_URL: "https://github.com/openresty/headers-more-nginx-module/archive/v0.33.tar.gz"
     TARGET_PATH: /usr/local/build/nginx-modules/headers-more-nginx-module
     UNTAR: true

Need help with deployments?

Contact Support

More Questions?

Join the Slack Channel