Configuring RubyYacht

All configuration in RubyYacht is done through a RubyYacht.configure block. This block allows you to run methods against RubyYacht::Configuration::DSL to add projects and define hooks. Once the block is done, all the changes are added into the shared RubyYacht.configuration object. You can run arbitrary code inside this block, but take note that the RubyYacht.configuration object will not be updated inside this block.

Example

You can see configuration_sample.rb for an example of what a full configuration file would look like.

Adding Projects

Inside a configure block, you can call project :apollo to add a project named apollo. The project method takes a block, which allows you to run methods against RubyYacht::Project::DSL to fill in the details of your project.

Project Fields

You can provide the following fields.

Name	Description	Example	Default
system_prefix	The prefix that is prepended before the names of the images and containers for this project.	`system_prefix :foo`	None; this is required.
repository	The host name for the code repository that holds the apps.	`repository 'github.com'`	None; this is required.
repository_protocol	The protocol that we use to check out the repositories. This can be `ssh`, `http`, or `https`.	`repository_protocol 'https'`	ssh
check_out_locally	Whether we should check out the code on the host system and map that directory into the docker container. If this is set to false, the code will not be easily accessible from the host system.	`check_out_locally # If you want to set it to true.`	False
primary_app	The name of the primary app that should be served from the main domain. If this is nil, then the main domain will server a landing page with a list of the apps, and the apps themselves will be accessed through subdomains.	`primary_app :mars`	nil

Inside a project block, you also define databases, DNS servers, web servers, and apps, as described below.

Plugin-Specific Fields

If you have loaded the Rails plugin, which is loaded by default, the project will also have the following fields:

Name Description Example Default

rails_environment The environment for the Rails apps. rails_environment 'development' development

rails_secret_key_base

Name	Description	Example	Default
rails_environment	The environment for the Rails apps.	`rails_environment 'development'`	development
rails_secret_key_base	The key for signing sessions and other app secrets in the Rails apps. You will probably want to keep this outside of your configuration scripts and outside of source control, so that it is kept secure and can be set to different values in different environments.	`rails_secret_key_base 'abc123'`	None; this is required
rails_excluded_gem_groups	The gem groups from the Gemfile that should not be installed on the server.	`rails_excluded_gem_groups %w(development test)`	An empty array

The key for signing sessions and other app secrets in the Rails apps.

You will probably want to keep this outside of your configuration scripts and outside of source control, so that it is kept secure and can be set to different values in different environments.

rails_secret_key_base 'abc123'

None; this is required

rails_excluded_gem_groups The gem groups from the Gemfile that should not be installed on the server. rails_excluded_gem_groups %w(development test) An empty array

For more information about working with the default plugins, see Default Plugins below.

Adding Apps

Inside the project DSL, you can call app :rails, :mars to add a Rails app called mars. You can also call rails_app :mars to do the same thing. Both forms take a block, which allows you to call methods from RubyYacht::App::DSL.

If you are using a different app type, you can supply that type instead of rails, but the app type must be defined through a plugin.

You can call the app method multiple times to add multiple databases.

App Fields

You can provide the following fields in the app DSL:

Name	Description	Example	Default
repository_name	The name of the code repository holding this app. This is relative to the project's repository. If this is nil, then the scripts will create a new app instead of trying to check out an existing one. When combined with the `check_out_locally` flag on the project, this can be a good way to bootstrap new apps.	`repository_name 'brownleej/mars'`	nil
database_name	The name of the database this app uses. If this is not provided, the app will not have any database configured automatically.	`database_name :apollo`	nil
port	The port the app listens on. Note: The app servers will only be accessible within the docker network; they will not be directly accessible from the host machine or the outside world. For this reason, all of your apps can share the same port without causing any conflicts.	`port 3000`	8080

Adding Databases

Inside the project DSL, you can call database :mysql, :apollo to add a MySQL database called apollo. You can also call mysql_database :apollo to do the same thing. Both forms take a block, which allows you to call methods from RubyYacht::Database::DSL.

You can call the database method multiple times to add multiple databases.

If you are using a different database type, you can supply that type instead of mysql, but the database type must be defined through a plugin.

Database Fields

Name	Description	Example	Default
host	The name of the host that the database server is on. If you provide `localhost`, this will create a database image and a database container for the database. If you provide any other value, this will not create any database image or container, and will only use the database config to point the apps toward the correct external server.	`host 'db1.test.com'`	None; this is required.
username	The name of the user that the apps will use to connect to the database.	`username 'apollo'`	None; this is required.
password	The password that the apps will use to connect to the database.	`password 'testpass'`	None; this is required.
port	The port that the database server listens on.	`port 3377`	In general, this does not have a default value. For MySQL databases, though, this will be set to 3306 by default.
container_label	The label for the images and containers for this database. For instance, if your project prefix is `apollo` and the container label for the database is `mysql`, the image and container for the database will be called `apollo-mysql`.	`container_label :mysql`	database

Adding Web Servers

The app containers will not publish their ports to the host machine or the outside world, so you need to define web servers that serve as a proxy for them. Inside the project DSL, you can call web_server :nginx to add an Nginx web server. You can also call nginx_web_server to do the same thing. Both forms take a block, which allows you to call methods from RubyYacht::WebServer::DSL.

By default, the web server will be called web, and its image name and container name will have the format apollo-web, where apollo is the system prefix for the project. If you want to use a different name, you can pass this as an argument to web_server or nginx_web_server.

You can call the web_server method multiple times to add multiple servers. The scripts will try to start all of the web servers for your projects at once, which will cause conflicts if they are trying to listen on the same port. This is also a potential problem if you have multiple projects in the same configuration file, since each project will need its own web server.

If you are using a different web server type, you can supply that type instead of nginx, but the server type must be defined through a plugin.

Name	Description	Example	Default
domain	The main domain for this server. Different apps will be added as subdomains of this main domain.	`domain 'test.com'`	None; this is required.
port	The port that this server listens on. This is the port on the host machine that the requests will come into. Inside the container, the server will always listen on port 80, and it will be mapped to this port= on the host.	`port 8080`	80

DNS Server Config

If your network has custom DNS servers, you can call dns_server inside of a project block to define your DNS server config. The dns_server method takes no arguents, but takes a block which allows you to call methods from RubyYacht::DnsServer::DSL.

You should only call the dns_server once for a given project.

DNS Server Fields

Name	Description	Example	Default
server	The hostname or IP address for the DNS server. You can call this multiple times to add multiple DNS servers	`server 'dns.test.com'`	Empty; no DNS servers
search_domain	The default search domains for server names. You can call this multiple times to add multiple search domains.	`search_domain 'db.test.com'`	Empty; no DNS search domains

Local Configuration

You may want to have some of your configuration stored in a local file, outside of source control, to handle host-specific settings. For instance, you may have different users using different remote databases, or you may want to set the Rails environment differently in production than in testing. You can do this through two steps. First, you can call add_local_config to load the configuration from the YAML file:

    RubyYacht.configure do
      add_local_config File.join(File.dirname(__FILE__), 'config.yml')
    end

This has to be done in a separate configuration block, because the loaded config will not be available until the configuration block is over.

Inside your main configuration block, you can then call copy_local_config to set the fields in the DSL based on the local config:

    project :apollo do
      system_prefix :apollo

      copy_local_config :rails_environment, :rails_secret_key_base
    end

You may also want to have some of your configuration fields grouped together to keep the config file neater. For instance, you can have a database section of the config YML file that is structured like this:

    :database:
      :apollo:
        :host: db1.apollo.com
        :username: apollo
        :password: ;kljfadsl
        :name: apollo_production

And then inside your project config, you could call:

    database :apollo do
      copy_local_config :host, :username, :password, :name, from: 'database.apollo'
    end

Default Plugins

By default, RubyYacht comes with three plugins, defined under the RubyYacht::Plugins namespace:

Rails, for defining app servers for Rails apps
MySQL, for defining MySQL database servers
Nginx, for defining Nginx web servers.

If you want to unload the default plugins, you can call RubyYacht.configuration.clear before defining the rest of your configuration. You can then load individual plugins by calling, for instance, RubyYacht::Plugins::MySQL.load.

Miscellaneous Configuration

The disable_docker_machine flag on RubyYacht.configuration forces the scripts to act as though docker-machine is not installed. This can be helpful if you are running a Docker for Mac or Docker for Windows beta alongside a docker-machine-based installation.