h1. !http://railsapps.github.io/images/rails-36x36.jpg(Rails Composer)! Rails Composer
An application template that creates starter applications for Rails.
It's the Rails generator on steroids.
Watch the videos:
|. |. | | !http://railsapps.github.io/images/rails-composer-mailing-list.png(Sign up for the Rails Composer mailing list)!:http://mailinglist.railscomposer.com/ | !http://railsapps.github.io/images/join/join-railsapps.png(Join the RailsApps Project)!:http://railsapps.github.io/ | | "Rails Composer mailing list":http://mailinglist.railscomposer.com/ | "Support the project":http://railsapps.github.io/ |
h4. From the RailsApps Project
The "RailsApps":http://railsapps.github.io/ open source project offers starter applications and tutorials for Rails developers. Generate the applications with the Rails Composer tool.
All the code is explained in the Capstone Rails Tutorials. You can purchase the "Capstone Rails Tutorials":https://tutorials.railsapps.org/ to support the project.
"Sign up for the Rails Composer mailing list":http://mailinglist.railscomposer.com/ for news and announcements.
h2. Starter Apps and Tutorials
|. Example |. Tutorial |_. Comments | | "learn-rails":https://github.com/RailsApps/learn-rails | "Learn Ruby on Rails":http://learn-rails.com/learn-ruby-on-rails.html | from the book for beginners | | "rails-bootstrap":https://github.com/RailsApps/rails-bootstrap | "Rails and Bootstrap":http://railsapps.github.io/twitter-bootstrap-rails.html | Bootstrap front-end framework | | "rails-foundation":https://github.com/RailsApps/rails-foundation | "Rails and Foundation":http://railsapps.github.io/rails-foundation.html | Foundation front-end framework | | "rails-mailinglist-activejob":https://github.com/RailsApps/rails-mailinglist-activejob | "Mailing List with Active Job Tutorial":https://tutorials.railsapps.org/ | sign up for a mailing list using background processing | | "rails-omniauth":https://github.com/RailsApps/rails-omniauth | "OmniAuth Tutorial":https://tutorials.railsapps.org/ | authentication with OmniAuth | | "rails-devise":https://github.com/RailsApps/rails-devise | "Rails Devise Tutorial":https://tutorials.railsapps.org/ | authentication with Devise | | "rails-devise-roles":https://github.com/RailsApps/rails-devise-roles | "Role-Based Authorization":https://tutorials.railsapps.org/ | authorization with roles | | "rails-devise-pundit":https://github.com/RailsApps/rails-devise-pundit | "Rails Pundit Tutorial":https://tutorials.railsapps.org/ | authorization with Pundit | | "rails-signup-download":https://github.com/RailsApps/rails-signup-download | "Rails Signup Download":https://tutorials.railsapps.org/ | Devise plus download a PDF file | | "rails-stripe-checkout":https://github.com/RailsApps/rails-stripe-checkout | "Stripe Checkout":https://tutorials.railsapps.org/ | selling a product with Stripe Checkout | | "rails-stripe-coupons":https://github.com/RailsApps/rails-stripe-coupons | "Stripe JS With Coupons":https://tutorials.railsapps.org/ | complex Rails and Stripe integration |
h4. The rails_apps_composer Gem
Do you want to customize the Rails Composer application template? The Rails Composer application template is built from recipes provided by the "rails_apps_composer":https://github.com/RailsApps/rails_apps_composer gem.
h4. If You Are New to Rails
If you're new to Rails, see "What is Ruby on Rails?":http://railsapps.github.io/what-is-ruby-rails.html, the book "Learn Ruby on Rails":http://learn-rails.com/learn-ruby-on-rails.html, and recommendations for a "Rails tutorial":https://tutorials.railsapps.org/rails-tutorial.
h2. Dependencies
Before running the Rails Composer tool, you need to install:
Check that appropriate versions of Ruby and Rails are installed in your development environment: @$ ruby -v@ @$ rails -v@
Be sure to read the article "Installing Rails":http://railsapps.github.io/installing-rails.html to make sure your development environment is set up properly.
h2. How To Use Rails Composer
To build a Rails application using the Rails Composer tool:
$ rails new myapp -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
Replace @myapp@ with the name of your application.
The @$@ character indicates a shell prompt; don't include it when you run the command.
See the "Troubleshooting" section below if you see errors. In general, you'll avoid problems if you create your application using RVM as described in the next section.
h3. Creating a Starter App Using RVM
I recommend using "RVM":https://rvm.io/, the Ruby Version Manager, to manage your Rails versions, as described in the "Installing Rails":http://railsapps.github.io/installing-rails.html article.
Here's how to generate a new Rails application using the Rails Composer tool and RVM:
$ mkdir myapp $ cd myapp $ rvm use ruby-2.4.0@myapp --ruby-version --create $ gem install rails $ rails new . -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
Instead of installing Rails into the global gemset and running @rails new@, we'll create a root directory for a new application, create a new gemset, install Rails, and then generate a starter application.
When we create the gemset, the option "--ruby-version" creates .ruby-version and .ruby-gemset files in the root directory. RVM recognizes these files in an application's root directory and loads the required version of Ruby and the correct gemset whenever you enter the directory.
When we create the gemset, it will be empty (though it inherits use of all the gems in the global gemset). We immediately install Rails. The command @gem install rails@ installs the most recent stable release of Rails.
Finally we run @rails new .@. We use the Unix "dot" convention to refer to the current directory. This assigns the name of the directory to the new application.
This approach is different from the way most beginners are taught to create a Rails application. Our approach makes it easy to create a project-specific gemset to avoid clashes between gem versions when using the Rails Composer tool.
h2. Choose a RailsApps Starter Application
Use Rails Composer to generate any of the example applications from the "RailsApps project":http://railsapps.github.io/. You'll be able to choose your own project name when you generate the app. Generating the application gives you additional options.
To build the example application, Rails must be installed in your development environment.
You'll see a prompt:
option Build a starter application? 1) Build a RailsApps example application 2) Contributed applications 3) Custom application
Enter "1" to select Build a starter application. You'll see a prompt:
option Choose a starter application. 1) learn-rails 2) rails-bootstrap 3) rails-foundation 4) rails-mailinglist-activejob 5) rails-omniauth 6) rails-devise 7) rails-devise-roles 8) rails-devise-pundit 9) rails-signup-download 10) rails-stripe-checkout 11) rails-stripe-coupons
Each of these applications is available as an example in the "RailsApps GitHub repo":https://github.com/RailsApps and each is accompanied by a tutorial on the "Capstone Rails Tutorials":https://tutorials.railsapps.org/ site.
Make your choice. The Rails Composer tool may give you other options (other applications may have been added since these notes were written).
h4. Options
The application generator template will ask you for additional preferences. Options vary, depending on the example application you build. Options may have changed in a newer version of Rails Composer.
option Web server for development? 1) WEBrick (default) 2) Thin 3) Unicorn 4) Puma 5) Phusion Passenger (Apache/Nginx) 6) Phusion Passenger (Standalone) option Web server for production? 1) Same as development 2) Thin 3) Unicorn 4) Puma 5) Phusion Passenger (Apache/Nginx) 6) Phusion Passenger (Standalone) option Database used in development? 1) SQLite 2) PostgreSQL 3) MySQL option Template engine? 1) ERB 2) Haml 3) Slim option Test framework? 1) None 2) RSpec with Capybara option Front-end framework? 1) None 2) Bootstrap 3.0 3) Bootstrap 2.3 4) Zurb Foundation 5.0 5) Zurb Foundation 4.0 6) Simple CSS option Install page-view analytics? 1) None 2) Google Analytics 3) Segment.io extras Set a robots.txt file to ban spiders? (y/n) extras Create a GitHub repository? (y/n) extras Use or create a project-specific rvm gemset? (y/n)
h4. Web Servers
If you plan to deploy to Heroku, select Puma as your production webserver. Puma is recommended by Heroku.
h4. Database
Choose "SQLite" for the easiest setup. If you choose PostgreSQL or MySQL, the databases must be installed and running before you run Rails Composer.
h4. Template Engine
The example applications use the default "ERB" Rails template engine. Optionally, you can use another template engine, such as Haml or Slim. See instructions for "Haml and Rails":http://railsapps.github.io/rails-haml.html.
h4. Testing
If you are a beginner, select "None." Select "RSpec with Capybara" if you want tests.
h4. Front-end Framework
If you choose a front-end framework, you'll get an application layout file, plus navigation and flash messages, styled with a default theme.
h4. Other Choices
Set a robots.txt file to ban spiders if you want to keep your new site out of Google search results.
If you choose to create a GitHub repository, the generator will prompt you for a GitHub username and password.
It is a good idea to use "RVM":https://rvm.io/, the Ruby Version Manager, and create a project-specific rvm gemset (not available on Windows). See "Installing Rails":http://railsapps.github.io/installing-rails.html.
h2. Contributed Applications
Currently, there are no contributed applications available. If you would like to add your favorite starter application to Rails Composer, open an issue to let us know.
h2. Build Your Own Application
If you choose "Custom application," you will get a wide set of choices. Not all are actively supported.
A large community of developers contributes code that supports additional gems and favorite configurations offered with the "build your own options." However, not all contributions are actively maintained. That means not all options are tested or fully supported, so you may need to spend time debugging a "build your own application."
When you choose "Custom application," you will see something similar to this:
option Build a starter application? 1) Build a RailsApps example application 2) Contributed applications 3) Custom application option Web server for development? 1) WEBrick (default) 2) Thin 3) Unicorn 4) Puma 5) Phusion Passenger (Apache/Nginx) 6) Phusion Passenger (Standalone) option Web server for production? 1) Same as development 2) Thin 3) Unicorn 4) Puma 5) Phusion Passenger (Apache/Nginx) 6) Phusion Passenger (Standalone) option Database used in development? 1) SQLite 2) PostgreSQL 3) MySQL option Template engine? 1) ERB 2) Haml 3) Slim option Test framework? 1) None 2) RSpec with Capybara option Continuous testing? 1) None 2) Guard option Front-end framework? 1) None 2) Bootstrap 3.0 3) Bootstrap 2.3 4) Zurb Foundation 5.0 5) Zurb Foundation 4.0 6) Simple CSS option Add support for sending email? 1) None 2) Gmail 3) SMTP 4) SendGrid 5) Mandrill option Authentication? 1) None 2) Devise 3) OmniAuth option Devise modules? 1) Devise with default modules 2) Devise with Confirmable module option Authorization? 1) None 2) Pundit option Use a form builder gem? 1) None 2) SimpleForm option Install a starter app? 1) None 2) Home Page 3) Home Page, User Accounts 4) Home Page, User Accounts, Admin Dashboard extras Add 'therubyracer' JavaScript runtime (for Linux users without node.js)? (y/n) extras Set a robots.txt file to ban spiders? (y/n) extras Create a GitHub repository? (y/n) option Add gem and file for environment variables? 1) None 2) Add .env with Foreman 3) Add application.yml with Figaro extras Reduce assets logger noise during development? (y/n) extras Improve error reporting with 'better_errors' during development? (y/n) extras Use 'pry' as console replacement during development and test? (y/n) extras Use or create a project-specific rvm gemset? (y/n) option Add a deployment mechanism? 1) None 2) Capistrano3
h2. Run the Application
Switch to the application directory to examine and test what you've built.
$ cd myapp
h4. Quick Test
For a "smoke test" to see if everything runs, display a list of Rake tasks.
$ rake -T
There's no need to run @bundle exec rake@ instead of @rake@ when you are using rvm (see "rvm and bundler integration":https://rvm.io/integration/bundler/).
h4. Start the Web Server
If you've chosen WEBrick or Thin for your web server, can run the app by entering the command:
@$ rails server@
To see your application in action, open a browser window and navigate to "http://localhost:3000/":http://localhost:3000.
For the Unicorn web server:
@$ unicorn@
See the app at "http://localhost:8080/":http://localhost:8080.
For the Puma web server:
@$ rails server puma@
See the app at "http://localhost:3000/":http://localhost:3000.
For Phusion Passenger (Apache or Nginx integration mode), please refer to "the official documentation":https://www.phusionpassenger.com/documentation_and_support.
For Phusion Passenger (Standalone):
@$ passenger start@
h4. Login
If you've created a version of the application that sets up a default user, log in with:
You should delete or change any pre-configured logins before you deploy your application.
h2. Testing
Some versions of the starter application will contain a suite of RSpec feature and unit tests.
Run @rspec@ to run all RSpec tests.
Please send the author a message, create an issue, or submit a pull request if you want to contribute improved RSpec tests.
h2. Deployment
For easy deployment, use a “platform as a service” provider such as:
For deployment on Heroku, see the article:
h2. Troubleshooting
Problems? Please check both "issues for the Rails Composer tool":https://github.com/RailsApps/rails-composer/issues and the "issues for the rails_apps_composer gem":https://github.com/RailsApps/rails_apps_composer/issues.
You should review the article "Installing Rails":http://railsapps.github.io/installing-rails.html to make sure you've updated all the components that are required to run Rails successfully.
h4. Problems with "Could not be loaded... You have already activated..."
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 (…)”":http://railsapps.github.io/rails-error-you-have-already-activated.html.
h4. Problems with "Certificate Verify Failed"
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":http://railsapps.github.io/openssl-certificate-verify-failed.html.
h4. Problems with "Segmentation Fault"
If you get a "segfault" when you try @rails new@, try removing and reinstalling rvm.
h2. Application Template Default
The @rails new@ command creates a new Rails application. If you want to use the Rails Composer 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 template when you create a new Rails application:
# ~/.railsrc -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
h2. Documentation and Support
The Rails Composer application template is assembled from recipes supplied by the "rails_apps_composer":https://github.com/RailsApps/rails_apps_composer gem. See the rails_apps_composer project to understand how the Rails Composer application works.
h4. Customizing the Template
If you wish to change the template to generate an app with your own customized options, you can copy and edit the template file. However, it is better to use the "rails_apps_composer":https://github.com/RailsApps/rails_apps_composer gem to create a new application template. You'll find newer versions of the recipes that make up the application template. You may find issues have been identified and (perhaps) fixed. And it will be easier to maintain your application template if you work from the "rails_apps_composer":https://github.com/RailsApps/rails_apps_composer gem.
h4. Writing Recipes
To understand the code in these templates, take a look at "Thor::Actions":http://rdoc.info/github/wycats/thor/master/Thor/Actions. Your recipes can use any methods provided by "Thor::Actions":http://rdoc.info/github/wycats/thor/master/Thor/Actions or "Rails::Generators::Actions":http://railsapi.com/doc/rails-v3.0.3/classes/Rails/Generators/Actions.html. A big thanks to Yehuda Katz for "creating Thor":http://yehudakatz.com/2008/05/12/by-thors-hammer/.
h4. About Rails Application Templates
There is an unfinished Rails Guide on "Rails Application Templates":https://github.com/rails/rails/blob/master/guides/source/rails_application_templates.md.
Also see:
"Cooking Up A Custom Rails 3 Template (11 Oct 2010) by Andrea Singh":http://blog.madebydna.com/all/code/2010/10/11/cooking-up-a-custom-rails3-template.html "Rails Application Templates (16 Sept 2010) by Collin Schaafsma":http://quickleft.com/blog/rails-application-templates "Application templates in Rails 3 (18 Sept 2009) by Ben Scofield":http://benscofield.com/2009/09/application-templates-in-rails-3/ "Railscasts: App Templates in Rails 2.3 (9 Feb 2009) by Ryan Bates":http://railscasts.com/episodes/148-app-templates-in-rails-2-3 "Rails templates (4 Dec 2008) by Pratik Naik":http://m.onkey.org/rails-templates
h4. Similar Projects
There are many similar projects:
h4. Issues
Problems? Please check both "issues for the Rails Composer tool":https://github.com/RailsApps/rails-composer/issues and the "issues for the rails_apps_composer gem":https://github.com/RailsApps/rails_apps_composer/issues.
h4. Where to Get Help
Your best source for help with problems is "Stack Overflow":http://stackoverflow.com/questions/tagged/railsapps. Your issue may have been encountered and addressed by others.
Use the tag "railsapps" on Stack Overflow for extra attention.
h2. Contributing
Please make changes to the "rails_apps_composer":https://github.com/RailsApps/rails_apps_composer gem rather than changing the Rails Composer application template.
h2. Credits
Daniel Kehoe initiated the "RailsApps project":https://github.com/RailsApps. The "rails_apps_composer":https://github.com/RailsApps/rails_apps_composer gem is derived from Michael Bleigh’s RailsWizard gem.
Is it useful to you? Follow the project on Twitter: "@rails_apps":http://twitter.com/rails_apps and tweet some praise. I'd love to know you were helped out by what I've put together.
h2. License
"MIT License":http://www.opensource.org/licenses/mit-license
Copyright 2012-14 Daniel Kehoe
h2. Useful Links
|. Getting Started |. Articles |_. Tutorials | | "Ruby on Rails":http://railsapps.github.io/ruby-and-rails.html | "Analytics for Rails":http://railsapps.github.io/rails-google-analytics.html | "Rails Bootstrap":http://railsapps.github.io/twitter-bootstrap-rails.html | | "What is Ruby on Rails?":http://railsapps.github.io/what-is-ruby-rails.html | "Heroku and Rails":http://railsapps.github.io/rails-heroku-tutorial.html | "Rails Foundation":http://railsapps.github.io/rails-foundation.html | | "Learn Ruby on Rails":http://learn-rails.com/learn-ruby-on-rails.html | "JavaScript and Rails":http://railsapps.github.io/rails-javascript-include-external.html | "RSpec Tutorial":http://railsapps.github.io/rspec.html | | "Rails Tutorial":https://tutorials.railsapps.org/rails-tutorial | "Rails Environment Variables":http://railsapps.github.io/rails-environment-variables.html | "Rails Devise Tutorial":http://railsapps.github.io/tutorial-rails-devise.html | | "Ruby on Rails Tutorial for Beginners":http://learn-rails.com/ruby-on-rails-tutorial-for-beginners | "Git and GitHub with Rails":http://railsapps.github.io/rails-git.html | "Devise RSpec":http://railsapps.github.io/tutorial-rails-devise-rspec-cucumber.html | | "Install Ruby on Rails":http://railsapps.github.io/installing-rails.html | "Send Email with Rails":http://railsapps.github.io/rails-send-email.html | "Devise Bootstrap":http://railsapps.github.io/tutorial-rails-bootstrap-devise-cancan.html | | "Install Ruby on Rails - Mac OS X":http://railsapps.github.io/installrubyonrails-mac.html | "Haml and Rails":http://railsapps.github.io/rails-haml.html | "Rails Membership Site with Stripe":https://tutorials.railsapps.org/rails-stripe-membership-saas | | "Install Ruby on Rails - Ubuntu":http://railsapps.github.io/installrubyonrails-ubuntu.html | "Rails Application Layout":http://railsapps.github.io/rails-default-application-layout.html | "Rails Subscription Site with Recurly":https://tutorials.railsapps.org/rails-recurly-subscription-saas | | "Ruby on Rails - Nitrous.io":http://railsapps.github.io/rubyonrails-nitrous-io.html | "HTML5 Boilerplate for Rails":http://railsapps.github.io/rails-html5-boilerplate.html | "Startup Prelaunch Signup Application":https://tutorials.railsapps.org/rails-prelaunch-signup | | "Update Rails":http://railsapps.github.io/updating-rails.html | "Example Gemfiles for Rails":http://railsapps.github.io/rails-3-2-example-gemfile.html | | "Rails Composer":http://railsapps.github.io/rails-composer/ | "Rails Application Templates":http://railsapps.github.io/rails-application-templates.html | | "Rails Examples":http://railsapps.github.io/ | "Rails Product Planning":http://railsapps.github.io/rails-product-planning.html | | "Rails Starter Apps":http://railsapps.github.io/rails-examples-tutorials.html | "Rails Project Management":http://railsapps.github.io/rails-project-management.html |