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.
domain The main domain for this project. Different apps will be added as subdomains of this main domain. domain 'test.com' None; this is required.
repository The host name for the code repository that holds the apps. repository 'github.com' None; this is required.
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, 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

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

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

Adding Apps

Inside the project DSL, you can call app :mars, :rails 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. repository_name 'brownleej/mars' None; this is required
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 :apollo, :mysql 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 app type, you can supply that type instead of mysql, but the app 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.
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

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

Default Plugins

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

  • Rails, for defining app servers for Rails apps
  • MySQL, for defining MySQL database 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.