Plugins

RubyYacht's plugin engine allows you to define your own server types, and add custom hooks for what happens when building images and running containers.

You can define server types and hooks inside of a RubyYacht.configure block. Like other parts of the configuration, they will not be committed until the configure block is over. The app and database DSLs require that the server types be committed, so you should add server types in a separate configuration block from the one where you define your projects.

Adding Server Types

You can call server_type :mongo to define a server type called mongo. The server_type method takes a block, which allows you to call methods from RubyYacht::ServerType::DSL.

Server Type Fields

You can add the following fields to fill out the server type:

Name	Description	Example	Default
container_type	The type of container that this server type applies to. This can be `app`, `database`, or `web`.	container_type :app	None; this is required.
baseline_image	The docker image that we should use as the baseline for the images for these servers. This is currently ignored for database images, since those are built off of the app dependencies image.	baseline_image 'ruby:2.3'	None; this is required.
project_attribute	This defines an attribute that can be set on a project. This can be set on any project once the server type has been loaded. This accepts hash of options. The currently accepted options are `name` and `default`. The full name of the attribute will be prefixed with the name of the server type, to keep server types from defining conflicting attributes.	project_attribute name: :environment, default: 'staging'	None; no custom project attributes
server_attribute	This defines an attribute that can be set on a server. This can be set on any server of the matching type once the server type has been loaded. This accepts hash of options. The currently accepted options are `name` and `default`. The full name of the attribute will be prefixed with the name of the server type, to keep server types from defining conflicting attributes.	server_attribute name: :key	None; no custom server attributes
server_default	This defines a default value for an existing attribute on servers of this type. This accepts hash of options. The keys in this hash are the names of the attributes, and the values are the default values. You can call this multiple times, and it will add the new defaults to the list.	server_default port: 3000	None; no custom default values.

Adding Hooks

To define a hook, you can call before, during, or after, followed by an event type. A before-hook is run before the event happens, an after-hook is run after the event happens, and a during-hook provides the logic for making an event happen.

These methods also take a block which allow you to call methods from RubyYacht::Hook::DSL.

Event Types

These are the event types that you can hook into:

Name	Description
startup	An app server is starting up.
build_checkout	The code for an app is being checked out when building an app image.
build_new_app	An app is being created from scratch rather than checked out from a repository.
install_libraries	The libraries for a server are being installed.
initialize_app_environment	The envrionment variables for the app-dependencies image are being set.
create_databases	The databases for a database server are being created.
load_database_seeds	The seed data for the app is being loaded on the database server.
add_project_landing	We are adding the configuration for a project's landing page to a web server.
add_app_config	We are adding the configuration for a single app to a web server.

Fields

The hook DSL allows you to set the following fields:

Name	Description	Example	Default
container_type	The name of the container type that this hook applies to	container_type :app	None; this is required
app_server_type	The name of the app server type that this hook applies to	app_server_type :rails	all, meaning all app server types
database_server_type	The name of the database server type that this hook applies to	database_server_type :mysql	all, meaning all database server types
web_server_type	The name of the web server type that this hook applies to	web_server_type :nginx	all, meaning all web server types
script_folder	The path to the folder in the host machine containing files to copy for this hook.	script_folder './scripts'	The working directory

You can constrain a hook by multiple types of servers at once.. For instance, you can set the app_server_type to :rails and the database_server_type to :mysql to specify that the hook only applies to Rails apps backed by a MySQL database. By default, hooks apply to all server types. You also have to specify the container_type to say whether the hook is triggered by events on app images, database images, or web server images. For instance, both app images and database images have a startup event, and they'll need different behaviors defined.

You can define the behaviors for the hooks with these methods:

Method Name	Description	Example
command	The shell command that should be run when the hook executes	command 'cp /var/docker/database.yml /var/code/config/'
copy_file	The name of a file that should be copied from the host machine into the image. This is relative to the hook's script folder.	copy_file 'setup.rb'
run_script	This specifies that this hook runs a script from the host machine. This will set the `copy_file` and the `command`.	run_script 'setup.rb'
set_environment_variable	This sets an environment variable in the image. The value can be set in either a block or a literal value passed as the second parameter.	set_environment_variable 'RAILS_ENV' do @project.rails_environment end

Setting Defaults

Your plugins will likely have many hooks that are using some of the same settings, so you can set defaults for them by calling add_hooks. This method takes a hash containing options for the hooks, and a block for adding them. Any hooks added in the block will have those options set.

The supported options are script_folder, app_server_type, database_server_type, web_server_type, and container_type.