Rails Apps Composer

The Rails Apps Composer gem installs a command line tool to assemble a Rails application from a collection of “recipes.”

What you can do with the rails_apps_composer gem:

• create a starter app from the command line
• make a reusable application template

You can use local recipes as well as recipes supplied with the gem.

The Rails Composer tool is built with the rails_apps_composer gem. The Rails Composer tool creates the example applications for the RailsApps project.

The Guide to the Rails Apps Composer Gem provides complete documentation:

• Overview
• Recipes
• Usage
• Diagnostics
• Hacking the Gem
• Anatomy of a Recipe
• Architecture
• Defaults File

Any issues? Please create a GitHub issue.

The RailsApps project provides example applications that developers use as starter apps. Hundreds of developers use the apps, report problems as they arise, and propose solutions. Rails changes frequently; each application is known to work and serves as your personal “reference implementation” so you can stay up to date. Each is accompanied by a tutorial so there is no mystery code. Maintenance and development of the RailsApps applications is supported by subscriptions to the RailsApps tutorials.

Follow the project on Twitter: @rails_apps. Tweet some praise if you like what you’ve found.

See the CHANGELOG for details.

If your favorite recipe is missing, please fork the repo, add the recipe and test it, then submit a pull request. I’m happy to add new recipes.

This gem is for experienced Rails developers who need a tool to create and maintain a Rails starter app or Rails application template. If you’re regularly building Rails applications that use certain popular gems or rely on common functionality such as authentication, you can benefit from the rails_apps_composer gem.

If you are new to Rails, try the Rails Composer tool instead. It provides an application template that is generated from the rails_apps_composer gem’s core recipes. The Rails Composer tool is easier to use. Use the rails_apps_composer gem if you want a custom application template, a custom combination of recipes, or the convenience of setting a defaults file.

See the CONTRIBUTING file for details about how you can contribute fixes or new features.

The rails_apps_composer gem is derived from Michael Bleigh’s RailsWizard gem. Early versions of the rails_apps_composer gem were a close fork of Michael Bleigh’s gem; rails_apps_composer 2.0 differs substantially. Other notable alternatives are Dr. Nic Williams’s App Scrolls and Daniel Davey’s app_drone. See a list of Rails Application Template Projects, particularly a list of “Application template-generating gems” for similar projects.

Before using the rails_apps_composer gem, you will need:

• The Ruby language (version 2.0.0)
• Rails 3.2 or Rails 4.0

The rails_apps_composer program uses the version of Rails that is currently installed when you launch the program. If you want to use the newest Rails version, upgrade before running rails_apps_composer.

See the article Installing Rails for advice about updating Rails and your development environment. You’ll avoid many potential headaches if you review the article step by step before beginning development.

Unless you use SQLite, which runs by default on Mac OS X, you’ll need to have a database server running before you run rails_apps_composer. This is true if you want to use PostgreSQL, MySQL, or MongoDB. I recommend using SQLite if you don’t want to set up a database server.

I recommend installing and using RVM, the Ruby Version Manager, to create a new gemset for rails_apps_composer. Using an RVM gemset will make it easier to identify and isolate incompatibilities among gems. RVM will install Ruby and set up a global gemset with a minimal set of gems.

Here’s how to generate a new Rails application using rails_apps_composer and RVM:

$ mkdir myapp
$ cd myapp
$ rvm use ruby-2.0.0@myapp --ruby-version --create
$ gem install rails
$ gem install rails_apps_composer
$ rails_apps_composer new . -r core

This approach avoids conflicts with outdated gem versions that may be active in your shell environment.

You may have trouble if you install the rails_apps_composer gem by including it in a Gemfile and running Bundler (reported in issue 114).

These commands are summarized here for your reference. See the Guide to the Rails Apps Composer Gem for details.

You can list recipes with short descriptions:

$ rails_apps_composer list

controllers    # Add controllers needed for starter apps.
core           # Select all core recipes.
email          # Configure email accounts.
example        # Example of a recipe.
extras         # Various extras.
frontend       # Install a front-end framework for HTML5 and CSS.
gems           # Add the gems your application needs.
git            # Initialize git for your application.
init           # Set up and initialize database.
models         # Add models needed for starter apps.
railsapps      # Install RailsApps example applications.
readme         # Build a README file for your application.
routes         # Add routes needed for starter apps.
setup          # Make choices for your application.
testing        # Add testing framework.
views          # Add views needed for starter apps.

The above list is current for rails_apps_composer 2.1; later releases will contain more recipes.

See the Guide for more detailed descriptions of recipes. You can find all available recipes in the repository recipes directory. Examining the recipe source code is the very best way to learn what a recipe will do.

I recommend selecting the core recipe if you are just getting started. The core recipe installs a collection of the most useful recipes.

The order in which you input a list or recipes determines the order of execution unless a recipe contains a requires or run_after directive.

A recipe may contain a requires directive which specifies other recipes which must be present before a recipe can run. The requires constraint will force the rails_apps_composer program to load any required recipes, even if you don’t add them explicitly.

Recipes may also contain a run_after directive. The rails_apps_composer program will organize the order of execution so that any recipes in the run_after list will execute earlier. That is, the recipe will run after everything else in the list.

In general, it’s best to add (or list) recipes in the order they should execute as some recipes may not contain a necessary requires or run_after directive.

See the Anatomy of a Recipe section in the Guide to learn about the format of a recipe.

If you plan to use RSpec instead of Test::Unit, or use an ORM such as Mongoid instead of Active Record, you must pass the -T or -O flags to the program so it will skip Test::Unit or Active Record.

The rails_apps_composer program will ask if you want to skip Test::Unit or Active Record when you generate an application interactively.

Any recipe can set the -T or -O arguments using the args directive.

Also, you can set -T or -O arguments in the defaults file.

Setting -T or -O arguments has no affect on application templates. An application template runs after the rails new command so it cannot set the -T or -O arguments. When you generate an application template, the program will not ask if you want to skip Test::Unit or Active Record.

You can use local recipes you’ve created yourself by using the -l flag and supplying the name of a directory that contains local recipes. The -l flag can be combined with any other command so you can create applications or application templates, interactively or from a defaults file.

For example, generate an application interactively using local recipes:

$ rails_apps_composer new myapp -l ~/recipes/

If you create local recipes, please consider contributing them to the project.

If you want to only use your local recipes, and not include the default recipes, use the -L flag.

You’ll be prompted for recipes and gems:

$ rails_apps_composer new myapp

Would you like to skip Test::Unit? (yes for RSpec) (y/n)
Would you like to skip Active Record? (yes for MongoDB) (y/n)

Available Recipes:
collections: core
configuration: email, gems, git, railsapps, readme, setup
example: example
frontend: frontend
initialize: init
mvc: controllers, models, routes, views
other: extras
testing: testing

Which recipe would you like to add? (blank to finish)
What gem would you like to add? (blank to finish)

Generating basic application, using:
"rails new myapp -m <temp_file>"

If you want to skip the prompts asking about Test::Unit and Active Record, you can set these arguments in a defaults file.

You will be able to choose recipes that are contained in the rails_apps_composer gem plus any local recipes you’ve added with the -l argument.

Choose the core recipe if you are not sure which recipes to select.

You can specify any gem. Any string you enter will be added as a gem in the starter app Gemfile.

If you want to skip the prompts asking which recipe or gem you’d like to add, use the “quiet flag” parameter on the command line by adding -q.

Provide a list of recipes using the -r flag. In this example, the core recipe selects all available core recipes:

$ rails_apps_composer new myapp -r core

Would you like to skip Test::Unit? (yes for RSpec) (y/n)
Would you like to skip Active Record? (yes for MongoDB) (y/n)
What gem would you like to add? (blank to finish)

Generating basic application, using:
"rails new myapp -m <temp_file>"

The program will prompt you for your preferences before generating an application (unless you set the “quiet flag” -q).

Use a defaults file for recipes, preferences, and extra gems so you don’t have to provide them interactively. Then generate an application using the -d flag:

$ rails_apps_composer new myapp -d my_defaults.yaml

Use the my_defaults.yaml file to specify a list of recipes, preferences, and extra gems. You can use any name (and file extension) for the file. See the Defaults File section in the Guide concerning the format of the defaults file.

Use the “quiet flag” -q if you want to skip all prompts:

$ rails_apps_composer new myapp -q -d my_defaults.yaml

You may want an application template to share with others. For an example, see the Rails Composer project which is an application template generated from the rails_apps_composer core recipes.

Specify a filename for the template:

$ rails_apps_composer template ~/Desktop/template.rb

Available Recipes:
collections: core
configuration: email, gems, git, railsapps, readme, setup
example: example
frontend: frontend
initialize: init
mvc: controllers, models, routes, views
other: extras
testing: testing

Which recipe would you like to add? (blank to finish)
What gem would you like to add? (blank to finish)
Generating and saving application template...
Done.

The command with the template argument followed by a filename generates an application template. You can add additional recipes or gems when prompted.

Specify a filename for the template and provide a list of recipes:

$ rails_apps_composer template ~/Desktop/template.rb -r core

What gem would you like to add? (blank to finish)
Generating and saving application template...
Done.

The command with the template argument followed by a filename and a list of recipes generates an application template. Use the “quiet flag” -q if you want to skip all prompts.

Generate an application template using a defaults file and the -d flag:

$ rails_apps_composer template ~/Desktop/template.rb -d my_defaults.yaml

Use the my_defaults.yaml file to specify a list of recipes, preferences, and extra gems. You can use any name (and file extension) for the file. See the Defaults File section in the Guide concerning the format of the defaults file. Use the “quiet flag” -q if you want to skip all prompts.

If you want to generate an application template, but use your own layout to do so, you can use the -t flag to set the directory where your templates are. Look at the templates/ directory in this gem to see how your templates should look.

$ rails_apps_composer template ~/Desktop/template.rb -t ~/Desktop/my_templates

After you’ve created a template file, you can generate an application from a template at any time using the rails new command with the -m option:

$ rails new myapp -m ~/Desktop/template.rb

The application template will prompt you for any configuration preferences requested by the recipes.

The rails new command allows you to specify the -T -O flags to skip Test::Unit files and Active Record files when you use an application template.

$ rails new myapp -m ~/Desktop/template.rb -T -O

The rails new command with the -m option also allows you to specify an application template that can be downloaded via HTTP. This makes it possible to host a template on GitHub (for example) and allow anyone to generate an application from the hosted template. For example:

$ rails new myapp -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb

The rails_apps_composer program runs diagnostics to reveal whether you’ve picked recipes and preferences that are known to work together.

Hundreds of developers are using this gem to build starter apps. As you can see from the commit log, the gem is actively maintained and the collection of recipes is growing. There is a drawback to all this activity, however. No developer who uses the rails_apps_composer gem uses all the recipes. And it would be very difficult to test a recipe in every possible combination. Consequently, combining some recipes or preferences may not work.

The rails_apps_composer gem contains an internal database of combinations of recipes and preferences that are known to work together. If you’ve picked recipes and preferences that are known to work together, you’ll get a confirmation:

WOOT! The recipes you've selected are known to work together.
If they don't, open an issue for rails_apps_composer on GitHub.
WOOT! The preferences you've selected are known to work together.
If they don't, open an issue for rails_apps_composer on GitHub.

You’ll get a warning if you’ve picked a combination we don’t know about:

WARNING! The recipes you've selected might not work together.
Help us out by reporting whether this combination works or fails.
WARNING! The preferences you've selected might not work together.
Help us out by reporting whether this combination works or fails.

Go to the GitHub repository to create an issue and let us know if you’ve found a combination of recipes or preferences that work together. If you’ve found a combination that works together, we’ll update the gem’s internal database for the next public release.

It’s a good idea to include the “readme” recipe when you run rails_apps_composer. If you do, the application’s README file will contain a diagnostics report. Here’s an example of the diagnostics report:

Recipes:
["gems", "readme", "setup"]

Preferences:
{:database=>"sqlite", :templates=>"erb", :email=>"none"}

Please include the diagnostics report when you create an issue on GitHub.

Problems? You should review the article Installing Rails to make sure you’ve updated all the components that are required to run Rails successfully.

If you get an error like this:

Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
    composer  Running 'after bundler' callbacks.
The template [...] could not be loaded.
Error: You have already activated ..., but your Gemfile requires ....
Using bundle exec may solve this.

It’s due to conflicting gem versions. See the article Rails Error: “You have already activated (…)”.

Are you getting an error “OpenSSL certificate verify failed” when you try to generate a new Rails app from an application template? See suggestions to resolve the error Certificate Verify Failed.

If you get a “segfault” when you try rails new, try removing and reinstalling RVM.

The rails new command creates a new Rails application. If you want to use an application template for every Rails application you build, you can set options for the rails new command in a .railsrc file in your home directory. Here’s how to set up a .railsrc file to use the Rails Composer template when you create a new Rails application:

# ~/.railsrc
-m https://raw.github.com/RailsApps/rails-composer/master/composer.rb

See the Guide to the Rails Apps Composer Gem to learn how to customize the gem either for your own use or to share with others.

See the CONTRIBUTING file for details about how you can contribute fixes or new features.

Any issues? Please create an issue on GitHub. Reporting issues (and patching!) helps everyone.

If you include the readme recipe when you generate an application, the generated README file will contain a diagnostics report (unless the program aborts before the readme recipe runs). Please include the diagnostics report when you create an issue on GitHub.

Daniel Kehoe maintains this gem as part of the RailsApps project.

This gem is derived from Michael Bleigh’s RailsWizard gem. The original idea and the innovative implementation is the work of Michael Bleigh.

Please see the CHANGELOG for a list of contributors.

Is the gem useful to you? Follow the project on Twitter: @rails_apps. I’d love to know you were helped out by the gem.

MIT License

Copyright © 2012-2013 Daniel Kehoe