ruby_yacht 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f958d7dd279688e4f761cfabde4f10696fea04f1
-  data.tar.gz: 921dfd094b9fdea99292b7daf03abb92c3f47415
+  metadata.gz: 724d4833d4fccb763b4173463fd4d39a6c72b5af
+  data.tar.gz: 385d64ac428190fe57096eeb5382f03fd3de4099
 SHA512:
-  metadata.gz: 6dd1410db4ef7cda53b1d5029102176c49e259896cde6cc68f882d65a03f02404382a667aa6551eedc829540fa89be75c59845d50e401e680fdf703df31cbe2a
-  data.tar.gz: 529f3f2489158df1ec5e535955286fb4fbad23f310e67cb2ea86ed3fd783a98f442f490e8221eba69004e5f9d8123d6698d81a83d90c4be7914703289f8f4ebd
+  metadata.gz: 3acb66557ac774872c8548f5afc9bb3e9a0e5fa5b189e5c2846e19eed7e3afbe1f7ee3b7345140ace4ae838d5b2315f538a53745219896f7ee94a06b1c9f35d1
+  data.tar.gz: fad7d2289310ee0c3ffed0f02250d1c86060bdf0f64ea3c1190c343eaa05a965595e2b15aa3fdd54807f458303244807235d1aceae57031f449cc7578ff519f9

data/.gitignore

@@ -2,3 +2,5 @@ tmp
 *.gem
 doc/coverage
 doc/code
+doc/yard
+.yardoc

data/.rdoc_options

@@ -11,6 +11,7 @@ exclude:
 - "nohup.out"
 - "Gemfile"
 - "doc/coverage"
+- "doc/yard"
 hyperlink_all: false
 line_numbers: false
 locale: 

data/.yardopts

@@ -0,0 +1,4 @@
+-o doc/yard
+-m markdown
+-
+doc/*.md

data/README.md

@@ -27,8 +27,8 @@ Enter this in the file:
         
 Your `run.rb` file will have two parts: A configuration block and the `Runner`
 command. The configuration block defines your projects and your apps. You can
-read [configuration_sample.rb](https://github.com/brownleej/ruby-yacht/blob/master/doc/configuration_sample.rb)
-for more information on how the configuration DSL.
+read [the configuration documentation](/gems/ruby_yacht/file/doc/configuration.md)
+for more information on the configuration options.
 
 The runner command invokes a RubyYacht script based on the command information.
 
@@ -210,8 +210,16 @@ branch.
 If you run it for a branch that you already have checked out, it will pull down
 the latest changes from the repository.
 
+# Plugins and Customization
+
+RubyYacht has a [plugin API](/gems/ruby_yacht/file/doc/plugins.md) for
+customizing the behavior of your scripts. You can use plugins for defining new
+app types or database types, or for adding hooks for the built-in types. This
+plugin API is so powerful that all of the rails-specific and mysql-specific code
+in RubyYacht is provided through plugins.
+
 # Additional Information
 
 If you're interested in contributing to the project, you can find more
-information in [CONTRIBUTING.md](https://github.com/brownleej/ruby-yacht/blob/master/doc/CONTRIBUTING.md).
+information in [the contributing documentation](/gems/ruby_yacht/file/doc/contributing.md).
 You can also reach out to me on Twitter [@brownleej](https://twitter.com/brownleej)

data/doc/TODO.md

@@ -8,11 +8,13 @@ for open tickets.
   approach
 * Look into issues with running shell command that has its own command-line
   flags.
+* Create shorthands for loading config from external files.
 
 # Plugins
 
 * Better support for rails apps with no database
 * Configurable ports for database servers
+* Support for SQLite databases
 
 # More customization
 

data/doc/configuration.md

@@ -0,0 +1,301 @@
+# 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](https://github.com/brownleej/ruby-yacht/blob/master/doc/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.
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+    <th>Example</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td>system_prefix</td>
+    <td>
+      The prefix that is prepended before the names of the images and containers
+      for this project.
+    </td>
+    <td><code>system_prefix :foo</code></td>
+    <td>None; this is required.</td>
+  </tr>
+  <tr>
+    <td>domain</td>
+    <td>
+      The main domain for this project. Different apps will be added as
+      subdomains of this main domain.
+    </td>
+    <td><code>domain 'test.com'</code></td>
+    <td>None; this is required.</td>
+  </tr>
+  <tr>
+    <td>repository</td>
+    <td>
+      The host name for the code repository that holds the apps.
+    </td>
+    <td><code>repository 'github.com'</code></td>
+    <td>None; this is required.</td>
+  </tr>
+  <tr>
+    <td>check_out_locally</td>
+    <td>
+      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.
+    </td>
+    <td>
+      <code>check_out_locally # If you want to set it to true.</code>
+    </td>
+    <td>
+      False
+    </td>
+  </tr>
+  <tr>
+    <td>primary_app</td>
+    <td>
+      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.
+    </td>
+    <td>
+      <code>primary_app :mars</code>
+    </td>
+    <td>
+      nil
+    </td>
+  </tr>
+</table>
+
+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:
+
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+    <th>Example</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td>rails_environment</td>
+    <td>
+      The environment for the Rails apps.
+    </td>
+    <td><code>rails_environment 'development'</code></td>
+    <td>development</td>
+  </tr>
+  <tr>
+    <td>rails_secret_key_base</td>
+    <td>
+      <p>
+        The key for signing sessions and other app secrets in the Rails apps.
+      </p>
+      <p>
+        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.
+      </p>
+    </td>
+    <td><code>rails_secret_key_base 'abc123'</code></td>
+    <td>None; this is required</td>
+  </tr>
+</table>
+
+For more information about working with the default plugins, see
+[Default Plugins](#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](/gems/ruby_yacht/file/doc/plugins.md).
+
+You can call the `app` method multiple times to add multiple databases.
+
+### App Fields
+
+You can provide the following fields in the app DSL:
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+    <th>Example</th>
+    <td>Default</td>
+  </tr>
+  <tr>
+    <td>repository_name</td>
+    <td>
+      The name of the code repository holding this app. This is relative to the
+      project's repository.
+    </td>
+    <td><code>repository_name 'brownleej/mars'</code></td>
+    <td>None; this is required</td>
+  </tr>
+  <tr>
+    <td>database_name</td>
+    <td>
+      The name of the database this app uses. If this is not provided, the app
+      will not have any database configured automatically.
+    </td>
+    <td><code>database_name :apollo</code></td>
+    <td>nil</td>
+  </tr>
+  <tr>
+    <td>port</td>
+    <td>
+      <p>The port the app listens on.</p>
+      <p>
+        <strong>Note:</strong> 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.
+      </p>
+    </td>
+    <td><code>port 3000</code></td>
+    <td>8080</td>
+</table>
+
+# 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](/gems/ruby_yacht/file/doc/plugins.md).
+
+### Database Fields
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+    <th>Example</th>
+    <td>Default</td>
+  </tr>
+  <tr>
+    <td>host</td>
+    <td>
+      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.
+    </td>
+    <td><code>host 'db1.test.com'</code></td>
+    <td>None; this is required.</td>
+  </tr>
+  <tr>
+    <td>username</td>
+    <td>
+      The name of the user that the apps will use to connect to the database.
+    </td>
+    <td><code>username 'apollo'</code></td>
+    <td>None; this is required.</td>
+  </tr>
+  <tr>
+    <td>password</td>
+    <td>
+      The password that the apps will use to connect to the database.
+    </td>
+    <td><code>password 'testpass'</code></td>
+    <td>None; this is required.</td>
+  </tr>
+  <tr>
+    <td>container_label</td>
+    <td>
+      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`.
+    </td>
+    <td><code>container_label :mysql</code></td>
+    <td>database</td>
+  </tr>
+</table>
+
+# 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
+
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+    <th>Example</th>
+    <td>Default</td>
+  </tr>
+  <tr>
+    <td>server</td>
+    <td>
+      The hostname or IP address for the DNS server. You can call this
+      multiple times to add multiple DNS servers
+    </td>
+    <td><code>server 'dns.test.com'</code></td>
+    <td>Empty; no DNS servers</td>
+  </tr>
+  <tr>
+    <td>search_domain</td>
+    <td>
+      The default search domains for server names. You can call this multiple
+      times to add multiple search domains.
+    </td>
+    <td><code>search_domain 'db.test.com'</code></td>
+    <td>Empty; no DNS search domains</td>
+  </tr>
+</table>
+
+# 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`.

data/doc/configuration_sample.rb

@@ -27,14 +27,12 @@ RubyYacht.configure do
     rails_secret_key_base 'abc'
     
     # The configuration for the database the app uses.
-    database do
+    # The apps will share a database called apollo
+    mysql_database :apollo do
       # A database host of localhost tells ruby-yacht to build a database
       # container for the apps' local database.
       host "localhost"
       
-      # The apps will share a database called apollo
-      name "apollo"
-      
       # The credentials for accessing the database.
       username "apollo"
       password "test"
@@ -43,11 +41,13 @@ RubyYacht.configure do
     rails_app :mars do
       # This app's repository is at github.com/brownleej/mars
       repository_name 'brownleej/mars'
+      database_name :apollo
     end
     
     rails_app :saturn do
       # This app's repository is at github.com/brownleej/saturn
       repository_name 'brownleej/saturn'
+      database_name :apollo
     end
 
     # This indicates that apollo.docker.local should serve requests to the mars
@@ -63,7 +63,7 @@ RubyYacht.configure do
     repository "github.com"
     rails_secret_key_base 'abc'
     
-    database do
+    mysql_database :jupiter do
       # Because this host has a real domain, we will not build a database
       # container. The database at this host must be set up in advance with
       # the database and the credentials in this file.
@@ -71,17 +71,19 @@ RubyYacht.configure do
       # When the apps start, they will automatically run database migrations
       # against this database.
       host "db.test.com"
-      name "jupiter"
+
       username "jupiter"
       password "test"
     end
     
     rails_app :venus do
       repository_name 'brownleej/venus'
+      database_name :jupiter
     end
     
     rails_app :saturn do
       repository_name 'brownleej/saturn'
+      database_name :jupiter
     end
 
     # Because this project has no primary app, jupiter.docker.local will serve

data/doc/{CONTRIBUTING.md → contributing.md}

@@ -9,4 +9,4 @@ requires caution when developing and running tests. The tests contain extensive
 stubs to prevent them from interacting with a real docker environment, and you
 should use the same techniques in your own tests. I would also recommend that
 you run the tests within their own docker container. You can find tools for
-building such a container in [spec/docker](../spec/docker)
+building such a container in `spec/docker`.

data/doc/plugins.md

@@ -0,0 +1,230 @@
+# 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:
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+    <th>Example</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td>container_type</td>
+    <td>
+      The type of container that this server type applies to. This can be either
+      `app` or `database`.
+    </td>
+    <td>
+      <code>container_type :app</code>
+    </td>
+    <td>None; this is required.</td>
+  </tr>
+  <tr>
+    <td>baseline_image</td>
+    <td>
+      <p>
+        The docker image that we should use as the baseline for the images for
+        these servers.
+      </p>
+      <p>
+        This is currently only used for the app images.
+      </p>
+    </td>
+    <td>
+      <code>baseline_image 'ruby:2.3'</code>
+    </td>
+    <td>
+      None; this is required.
+    </td>
+  </tr>
+  <tr>
+    <td>project_attribute</td>
+    <td>
+      <p>This defines an attribute that can be set on a project.</p>
+      <p>
+        This can be set on any project once the server type has been loaded.
+      </p>
+      <p>
+        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.
+      </p>
+    </td>
+    <td><code>project_attribute name: :environment, default: 'staging'</code></td>
+    <td>None; no custom project attributes</td>
+  </tr>
+  <tr>
+    <td>server_attribute</td>
+    <td>
+      <p>This defines an attribute that can be set on a server.</p>
+      <p>
+        This can be set on any server of the matching type once the server type
+        has been loaded.
+      </p>
+      <p>
+        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.
+      </p>
+    </td>
+    <td><code>server_attribute name: :key</code></td>
+    <td>None; no custom server attributes</td>
+  </tr>
+  <tr>
+  <td>environment_variable</td>
+  <td>
+    <p>
+      A custom environment variable that is set in an image for this plugin.
+    </p>
+    <p>
+      This accepts two parameters (image and name), as well as a block. The
+      image is the type of image this is set on: app, app_dependencies, or
+      database. The block provides a value for the variable. The block will
+      have access to the context of the image we're building, as 
+      <code>@project</code>, <code>@app</code>, and <code>@database</code>.
+    </p>
+    <p>
+      An app type plugin can also provide custom environment variable for a
+      database server.
+    </p>
+    <p>
+      You can call this multiple times to define multiple environment variables.
+    </p>
+  </td>
+  <td>
+    <code>
+      environment_variable :app_dependencies, 'RAILS_ENV' do
+        @project.rails_environment
+      end
+    </code>
+  </td>
+  <td>None; no custom environment variables.</td>
+  </tr>
+</table>
+
+# 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:
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>startup</td>
+    <td>An app server is starting up.</td>
+  </tr>
+  <tr>
+    <td>build_checkout</td>
+    <td>
+      The code for an app is being checked out when building an app image.
+    </td>
+  </tr>
+  <tr>
+    <td>install_libraries</td>
+    <td>The libraries for an app or database server are being installed.</td>
+  </tr>
+  <tr>
+    <td>create_databases</td>
+    <td>The databases for a database server are being created.</td>
+  </tr>
+  <tr>
+    <td>load_database_seeds</td>
+    <td>The seed data for the app is being loaded on the database server.</td>
+  </tr>
+</table>
+
+### Fields
+
+The hook DSL allows you to set the following fields:
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Description</th>
+    <th>Example</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td>server_type</td>
+    <td>The name of the server type that this hook applies to</td>
+    <td><code>server_type :rails</code></td>
+    <td>None; this is required</td>
+  </tr>
+  <tr>
+    <td>command</td>
+    <td>The shell command that should be run when the hook executes</td>
+    <td><code>command 'cp /var/docker/database.yml /var/code/config/'</code></td>
+    <td>
+      None; this is required. However, it can also be set by calling
+      `run_script`.
+    </td>
+  </tr>
+  <tr>
+    <td>script_folder</td>
+    <td>
+      The path to the folder in the host machine containing files to copy for
+      this hook.
+    </td>
+    <td><code>script_folder './scripts'</code></td>
+    <td>The working directory</td>
+  </tr>
+  <tr>
+    <td>copy_file</td>
+    <td>
+      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.
+    </td>
+    <td><code>copy_file 'setup.rb'</code></td>
+    <td>None, meaning that no files are copied for this hook.</td>
+  </tr>
+  <tr>
+    <td>run_script</td>
+    <td>
+      This specifies that this hook runs a script from the host machine. This
+      will set the `copy_file` and the `command`.
+    </td>
+    <td><code>run_script 'setup.rb'</code></td>
+    <td>None; if you are not using this you must call `command` instead.</td>
+  </tr>
+</table>
+
+### 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` and `server_type`.

data/lib/ruby_yacht/dsl/database.rb

@@ -86,7 +86,7 @@ module RubyYacht
       ##
       # :method: container_label
       # You can call `container_label 'mysql'` to give this database a container
-      # name that is {project}-mysql.
+      # name that is (project)-mysql.
       add_attribute :container_label, :database
       
       creates_object Database

data/lib/ruby_yacht/dsl/hook.rb

@@ -114,6 +114,7 @@ module RubyYacht
         end
       end
       
+      # This method creates a Hook object from the DSL.
       def create_object
         @copied_file_path = File.join(@script_folder || '.', @copy_file) if @copy_file
         super

data/ruby_yacht.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |spec|
   spec.name         = 'ruby_yacht'
-  spec.version      = '0.4.3'
-  spec.date         = '2016-04-27'
+  spec.version      = '0.5.0'
+  spec.date         = '2016-05-05'
   spec.description  = "A DSL for building docker containers for a family of Rails apps"
   spec.summary      = "A DSL for building docker containers for a family of Rails apps"
   spec.authors      = ["John Brownlee"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_yacht
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - John Brownlee
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-27 00:00:00.000000000 Z
+date: 2016-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -64,13 +64,16 @@ files:
 - .rspec
 - .rubocop.yml
 - .travis.yml
+- .yardopts
 - Gemfile
 - Gemfile.lock
 - LICENSE
 - README.md
-- doc/CONTRIBUTING.md
 - doc/TODO.md
+- doc/configuration.md
 - doc/configuration_sample.rb
+- doc/contributing.md
+- doc/plugins.md
 - lib/ruby_yacht.rb
 - lib/ruby_yacht/dsl.rb
 - lib/ruby_yacht/dsl/app.rb