Deploy hooks - syntax & commands

What are deploy hooks?

Deploy hooks are scripts that allow you to automate actions at various points during the deployment process for your applications.

If you’ve never used hooks before, we have a tutorial that walks you through the basics. For more detailed examples of using hooks in practice please read the in-depth How-to Guide.

Debugging deploy hooks

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.

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.

The table below is arranged in the order in which each hook point occurs in the deployment process (from earliest to latest):

Hook point Description
first_thing The first thing that will happen on the server after the operating system is installed. A common use-case for this hook is to install custom packages that your application relies on.
before_agent Runs before the Cloud 66 agent is installed on your server
after_agent Runs after the Cloud 66 agent is installed on your server
before_x Runs before database and storage engine(s) are installed on your server. Accepted values for x: redis, mysql, postgresql, mongodb, elasticsearch, rabbitmq, glusterfs, influxdb
after_x Runs after database and storage engine(s) are installed on your server. If multiple engines are installed it will wait until all of them are completed. Accepted values for x: redis, mysql, postgresql, mongodb, elasticsearch, rabbitmq, glusterfs, influxdb
before_y Runs before replication is configured for the database server(s). Accepted values for y: glusterfs_config, redis_replication, mongodb_replication, mysql_replication, postgresql_replication
after_y Runs after replication has been configured for the database server(s). Accepted values for y: glusterfs_config, redis_replication, mongodb_replication, mysql_replication, postgresql_replication
before_data_mount Runs before data is mounted (GlusterFS only)
after_data_mount Runs right after data has been mounted in GlusterFS
custom_server Runs only on your custom servers
before_node Runs before we install Node on your server
after_node Runs directly after Node has been installed
before_nginx Runs before we install NGINX on your server
after_nginx Runs directly after we install NGINX on your server
before_z Runs before your application framework is installed on your server. Accepted values for z: rails, rack, sinatra, padrino
after_checkout When we create your server, your code is pulled directly from Git. Use this hook if you want to make a change to your code after it is pulled.
after_bundle Runs after the bundle command(s) but before other rake tasks, such as database migrations. Happens during the code deployment of your application. Note: Use this hook if you need to run commands that are invoked before the symlink is updated on the release path.
after_symlink Runs after the symbolic link to your current code folder has been created. Happens during the code deployment of your application. This is a suitable hook point for running rake tasks like db:migrate, db:seed and db:rollback
after_z Runs after your application framework (and everything web related) is installed on your server. Accepted values for z: rails, rack, sinatra, padrino
before_processes Runs before any custom processes (i.e. Procfile or simmilar)
after_processes Runs after any custom processes
last_thing This hook will run as the last thing that happens on your server. If you have multiple servers, this hook will only trigger when all of them reach this point.

Targets

Every deploy hook must have a target - a server or set of servers on which it must be executed. You can simply choose any to run the hook across your entire application, but you can also choose to run it on a specific type of server. The options are any, rails, mysql, postgresql, mongodb, redis, sinatra, padrino, custom.

If you set the target of a hook to anything other than any then you will need to pay attention to the run_on field. This determines whether the hook will be applied to a single server in that group (the default) or to all the servers in that group.

Hook types

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

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

Hook fields

Each hook type has a different set of hook fields available, with some shared fields. Please be careful to note that:

Hook fields: snippets

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 an application is deployed, and will re-occur until the application 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 application 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 (e.g. 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

Hook fields: commands

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 an application is deployed, and will re-occur until the application 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 application 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 (e.g. 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

Hook fields: inline scripts

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 application 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 an application is deployed, and will re-occur until the application 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 (e.g. 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

Hook fields: existing scripts

Field Description
HOOK TYPE: Existing Scripts (Rails/Node applications 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 application 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 an application is deployed, and will re-occur until the application 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 (e.g. 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
Need help with deployments?
Contact Support
More Questions?
Join the Slack Channel