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.