Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

remove copy of tutorial in repo (using new git-based wiki repo)

  • Loading branch information...
commit 49a78128bc534bea7609584a846d79136f70c523 1 parent 8d8e874
Daniel Kehoe fortuity authored
Showing with 0 additions and 681 deletions.
  1. +0 −681 TUTORIAL.textile
681 TUTORIAL.textile
View
@@ -1,681 +0,0 @@
-h1. Rails3-Mongoid-Devise
-
-This example app combines "Mongoid":http://mongoid.org/ with "Devise":http://github.com/plataformatec/devise to give you quick development without schemas or migrations plus ready-made authentication and user management. It gives you a skeleton or starter app you can deploy in minutes.
-
-h2. Help and More Information
-
-To keep up to date with development of this app, follow me on Twitter:
-"http://twitter.com/yaxdotcom":http://twitter.com/yaxdotcom.
-
-Any issues? Please create an "Issue":http://github.com/fortuity/rails3-mongoid-devise/issues on GitHub.
-
-h2. Tutorial
-
-This tutorial documents each step that you must follow to create this application. Every step is documented concisely, so a complete beginner can create this application without any additional knowledge. However, no explanation is offered for any of the steps, so if you are a beginner, you're advised to look for an introduction to Rails elsewhere. Refer to the "Rails Guides":http://guides.rubyonrails.info/ site for help if you are a beginner.
-
-h2. Generating the Application
-
-To create the application, you can follow each step in this tutorial and cut and paste the code into your own files. However, it may be easier to generate a new Rails app using the example as a template:
-
-@$ rails new app_name -m https://github.com/fortuity/rails3-mongoid-devise/raw/master/template.rb@
-
-bq. Generating a Rails application from an "HTTPS" URL does not work in Rails 3.0.3 (and earlier versions). Expect it to be fixed in Rails 3.0.4. For details about the problem, see the "GitHub Support Issue":http://support.github.com/discussions/site/2213-github-https-redirect-breaks-rails-application-generator-templates and the "Rails 3.0.4 Patch":https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/5926 that will fix it. In the meantime, use @$ git clone git(at)github.com:fortuity/rails3-mongoid-devise.git@ to get a copy of the application.
-
-This creates a new Rails app (with the @app_name@ you provide) on your computer. It includes everything in the example app (as described in the "tutorial":http://wiki.github.com/fortuity/rails3-mongoid-devise/tutorial-walkthrough). Then you can read through the tutorial with the code already on your computer.
-
-If you wish to "change the recipe" to generate the app with your own customized options, you can copy and edit the file *template.rb*.
-
-h2. Assumptions
-
-This tutorial is based on Rails 3.0.3, Mongoid (version 2.0.0.beta.20), and Devise 1.1.3.
-
-Before beginning this tutorial, you need to install
-
-* The Ruby language (version 1.8.7 or 1.9.2)
-* Rails (version 3.0.3)
-* A working installation of "MongoDB":http://www.mongodb.org/ (version 1.6.0 or newer)
-
-I recommend installing rvm, the "Ruby Version Manager":http://rvm.beginrescueend.com/, to manage multiple versions of Rails if you have a mix of Rails 3 and Rails 2 applications.
-
-If you are using rvm, you can see a list of the Ruby versions currently installed:
-@$ rvm list@
-
-Check that appropriate versions of Ruby and Rails are installed in your development environment:
-@$ ruby -v@
-@$ rails -v@
-
-If you don't have MongoDB installed on your computer, you'll need to install it and set it up to be always running on your computer (run at launch). On Mac OS X, the easiest way to install MongoDB is to install "Homebrew":http://mxcl.github.com/homebrew/ and then run the following:
-
-<pre>
-brew install mongo
-sudo mkdir -p /data/db
-sudo chmod -Rv 777 /data/
-</pre>
-
-h2. Create the Rails Application
-
-Open a terminal, navigate to a folder where you have rights to create files, and type:
-
-@$ rails new rails3-mongoid-devise@
-
-You may give the app a different name if you are building it for your own use. For this tutorial, we'll assume the name is "rails3-mongoid-devise."
-
-This will create a Rails application that uses a SQLite database for data storage. We'll modify it to use MongoDB.
-
-After you create the application, switch to its folder to continue work directly in that application:
-
-@$ cd rails3-mongoid-devise@
-
-Edit the README file to remove the standard Rails boilerplate. Add what you like (perhaps the name of your app?).
-
-h2. Set Up Source Control (Git)
-
-If you're creating an app for deployment into production, you'll want to set up a source control repository at this point. If you are building a throw-away app for your own education, you may skip this step.
-
-Check that git is installed on your computer:
-
-@$ git version@
-
-Rails 3 has already created a *.gitignore* file for you. You may want to modify it:
-
-<pre>
-.bundle
-db/*.sqlite3
-log/*.log
-tmp/**/*
-.DS_Store
-</pre>
-
-Initialize git and check in your first commit:
-
-@$ git init@
-@$ git add .@
-@$ git commit -m 'initial commit'@
-
-You can check your commit status at any time with:
-
-@$ git status@
-
-At this point you can check your local project into a remote source control repository. We'll assume you are using git with an account at GitHub.
-
-Check that your GitHub account is set up properly:
-
-@$ ssh git(at)github.com@
-
-Go to GitHub and create a new empty repository ("http://github.com/repositories/new":http://github.com/repositories/new) into which you can push your local git repo.
-
-Add GitHub as a remote repository for your project and push your local project to the remote repository:
-
-@$ git remote add origin git(at)github.com:YOUR_GITHUB_ACCOUNT/YOUR_PROJECT_NAME.git@
-@$ git push origin master@
-
-At each stage of completion, you should check your code into your local repository:
-
-@$ git commit -a -m "some helpful comment"@
-
-and then push it to the remote repository:
-
-@$ git push origin master@
-
-h2. Set Up Gems
-
-h3. About Required Gems
-
-The application uses the following gems. I recommend checking for newer versions of these gems before proceeding:
-
-* rails (version 3.0.3) "(check rubygems.org for the rails gem)":http://rubygems.org/gems/rails
-* mongoid (version 2.0.0.beta.20) "(Check rubygems.org for the mongoid gem)":http://rubygems.org/gems/mongoid
-* bson_ext (version 1.1.2) "(Check rubygems.org for the bson_ext gem)":http://rubygems.org/gems/bson_ext
-* devise (version 1.1.3) "(Check rubygems.org for the devise gem)":http://rubygems.org/gems/devise
-
-The app has been tested with the indicated versions. If you are able to build the app with a newer gem, please create an "issue":http://github.com/fortuity/rails3-mongoid-devise/issues on GitHub and I will update the app.
-
-h3. Set up Your Gemfile
-
-Edit the *Gemfile* file to look like this:
-
-<pre>
-source 'http://rubygems.org'
-
-gem 'rails', '3.0.3'
-gem 'mongoid', '2.0.0.beta.20'
-gem 'bson_ext', '1.1.2'
-gem 'devise', '1.1.3'
-# uncomment the next line if you wish to deploy to Heroku
-# gem 'heroku', '1.13.7'
-# uncomment the following lines if you wish to use Haml
-# gem 'haml', '3.0.24'
-# gem 'haml-rails', '0.3.4', :group => :development
-# the folowing gems are used to generate Devise views for Haml
-# gem 'hpricot', '0.8.3', :group => :development
-# gem 'ruby_parser', '2.0.5', :group => :development
-</pre>
-
-h3. Install the Required Gems
-
-Install the required gems on your computer:
-
-@$ bundle install@
-
-You can check which gems are installed on your computer with:
-
-@$ gem list --local@
-
-Keep in mind that you have installed these gems locally. When you deploy the app to another server, the same gems (and versions) must be available.
-
-h2. Configuration for Haml
-
-In this example, we'll use the default Rails template engine. Optionally, you can use another template engine, such as Haml. You'll need extra gems (commented in the *Gemfile*).
-
-With the haml-rails gem, there is no need to modify the *application.rb* file to accommodate Haml. Any time you generate a controller or scaffold, you'll get Haml instead of ERB templates. And when your Rails application loads, Haml will be loaded and initialized.
-
-h2. Use Mongoid
-
-Mongoid provides access to the MongoDB database from Rails. Set up Mongoid with:
-
-@$ rails generate mongoid:config@
-
-You can use the default configuration (found in the file *config/mongoid.yml*.)
-
-Configure your application to use Mongoid instead of the default ActiveRecord. Edit the file *config/application.rb* to look like this:
-
-<pre>
-require File.expand_path('../boot', __FILE__)
-
-# If you are deploying to Heroku and MongoHQ,
-# you supply connection information here.
-require 'uri'
-if ENV['MONGOHQ_URL']
- mongo_uri = URI.parse(ENV['MONGOHQ_URL'])
- ENV['MONGOID_HOST'] = mongo_uri.host
- ENV['MONGOID_PORT'] = mongo_uri.port.to_s
- ENV['MONGOID_USERNAME'] = mongo_uri.user
- ENV['MONGOID_PASSWORD'] = mongo_uri.password
- ENV['MONGOID_DATABASE'] = mongo_uri.path.gsub('/', '')
-end
-
-require 'mongoid/railtie'
-require 'action_controller/railtie'
-require 'action_mailer/railtie'
-require 'active_resource/railtie'
-require 'rails/test_unit/railtie'
-
-# If you have a Gemfile, require the gems listed there, including any gems
-# you've limited to :test, :development, or :production.
-Bundler.require(:default, Rails.env) if defined?(Bundler)
-
-module Rails3MongoidDevise
- class Application < Rails::Application
-
- config.generators do |g|
- g.orm :mongoid
- end
-
- # Configure the default encoding used in templates for Ruby 1.9.
- config.encoding = "utf-8"
-
- # Configure sensitive parameters which will be filtered from the log file.
- config.filter_parameters += [:password]
- end
-end
-</pre>
-
-Note that @require 'mongoid/railtie'@ must precede the other "require" statements.
-
-h3. Test the App
-
-You can check that your app runs properly 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. You should see the Rails default information page.
-
-Stop the server with Control-C.
-
-h2. Set Up Authentication
-
-h3. Set Up Configuration for Devise
-
-This app uses Devise for user management and authentication. Devise is at "http://github.com/plataformatec/devise":http://github.com/plataformatec/devise.
-
-We've already installed the Devise gem with the @$ bundle install@ command. Run the generator:
-
-@$ rails generate devise:install@
-
-which installs a configuration file:
-
-*config/initializers/devise.rb*
-
-and a localization file.
-
-Devise will recognize that you already have Mongoid installed and it will set its ORM configuration in the *config/initializers/devise.rb* file to include:
-
-@require 'devise/orm/mongoid'@
-
-Set up action_mailer in your development environment in the file
-
-*config/environments/development.rb*
-
-by changing:
-
-<pre>
-# Don't care if the mailer can't send
-# config.action_mailer.raise_delivery_errors = false
-</pre>
-
-and adding:
-
-<pre>
-### ActionMailer Config
-config.action_mailer.default_url_options = { :host => 'localhost:3000' }
-# A dummy setup for development - no deliveries, but logged
-config.action_mailer.delivery_method = :smtp
-config.action_mailer.perform_deliveries = false
-config.action_mailer.raise_delivery_errors = true
-config.action_mailer.default :charset => "utf-8"
-</pre>
-
-Set up action_mailer in your production environment in the file
-
-*config/environments/production.rb*
-
-by adding:
-
-<pre>
-config.action_mailer.default_url_options = { :host => 'yourhost.com' }
-### ActionMailer Config
-# Setup for production - deliveries, no errors raised
-config.action_mailer.delivery_method = :smtp
-config.action_mailer.perform_deliveries = true
-config.action_mailer.raise_delivery_errors = false
-config.action_mailer.default :charset => "utf-8"
-</pre>
-
-h3. Generate a Model and Routes for Users
-
-Devise can manage users and administrators separately, allowing two (or more) roles to be implemented differently. For this example, we just implement Users.
-
-Use Devise to generate models and routes for a User:
-
-<pre>
-$ rails generate devise User
-</pre>
-
-Devise will recognize that Mongoid is installed and set up the User model with
-
-<pre>
-include Mongoid::Document
-</pre>
-
-which must precede all other statements in the model.
-
-Devise will modify the *config/routes.rb* file to add:
-
-<pre>
-devise_for :users
-</pre>
-
-which provides a complete set of routes for user signup and login. If you run @rake routes@ you can see the routes that this line of code creates.
-
-h2. Customize the Application
-
-h3. Enable Users to Have Names
-
-By default, Devise uses an email address to identify users. We'll add a "name" attribute as well.
-
-We're using Mongoid so there is no need to set up migration files as we would with MySQL or SQLite.
-
-We'll modify the user model to allow a "name" to be included when adding or updating a record.
-
-You'll also want to prevent malicious hackers from creating fake web forms that would allow changing of passwords through the mass-assignment operations of update_attributes(attrs) and new(attrs). With the default Rails ActiveRecord, Devise adds
-
-<pre>
-attr_accessible :email, :password, :password_confirmation
-</pre>
-
-You'll need to add this yourself when using Mongoid.
-
-Modify the file *models/user.rb* and add:
-
-<pre>
-field :name
-validates_presence_of :name
-validates_uniqueness_of :name, :email, :case_sensitive => false
-attr_accessible :name, :email, :password, :password_confirmation
-</pre>
-
-This will allow users to be created (or edited) with a name attribute. When a user is created, a name and must be present and must be unique (not used before). Note that Devise (by default) will check that the email address and password are not blank.
-
-h3. Prevent Logging of Passwords
-
-We don't want passwords written to our log file. In Rails 2, we would change the file
-
-*controllers/application_controller.rb*
-
-to include:
-
-@filter_parameter_logging :password, :password_confirmation@
-
-In Rails 3, this is deprecated and instead we modify the file *config/application.rb* to include:
-
-@config.filter_parameters += [:password, :password_confirmation]@
-
-Note that filter_parameters is an array.
-
-h2. Create a Home Page
-
-h3. Remove the Default Home Page
-
-Delete the default home page from your application:
-
-@$ rm public/index.html@
-
-You may also want to modify the file public/robots.txt to prevent indexing by search engines if you plan to have a development version on a publicly accessible server:
-
-<pre>
-# To ban all spiders from the entire site uncomment the next two lines:
-User-Agent: *
-Disallow: /
-</pre>
-
-h3. Create a Home Controller and View
-
-Create the first page of the application. Use the Rails generate command to create a "home" controller and a "views/home/index" page.
-
-@$ rails generate controller home index@
-
-If you're using the default template engine, you'll find the file:
-
-*views/home/index.html.erb*
-
-If you're using Haml, you'll find the file:
-
-*views/home/index.html.haml*
-
-We'll assume you're using the default template engine for the remainder of this tutorial.
-
-Now, you have to set a route to your home page. Edit the file *config/routes.rb* and replace:
-
-@get "home/index"@
-
-with
-
-@root :to => "home#index"@
-
-h3. Test the App
-
-You can check that your app runs properly 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. You should see your new home page.
-
-Stop the server with Control-C.
-
-h2. Create a Default User
-
-h3. Set Up a Database Seed File
-
-You'll want to set up a default user so you can easily log in to test the app. Modify the file *db/seeds.rb* by adding:
-
-<pre>
-puts 'EMPTY THE MONGODB DATABASE'
-Mongoid.master.collections.reject { |c| c.name == 'system.indexes'}.each(&:drop)
-puts 'SETTING UP DEFAULT USER LOGIN'
-user = User.create! :name => 'First User', :email => 'user@test.com', :password => 'please', :password_confirmation => 'please'
-puts 'New user created: ' << user.name
-</pre>
-
-You can change the values for name, email, and password as you wish.
-
-h3. Seed the Database
-
-Add the default user to the MongoDB database by running the command:
-
-@$ rake db:seed@
-
-h2. Set Up a Demonstration of Devise
-
-At this point, you may want to know if the default user has been saved to the MongoDB database. You'll also want to see how Devise manages authentication.
-
-h3. Set Up the Home Controller and Home Page
-
-Modify the file *controllers/home_controller.rb* and add:
-
-<pre>
-def index
- @users = User.all
-end
-</pre>
-
-Modify the file *views/home/index.html.erb* and add:
-
-<pre>
-<% @users.each do |user| %>
- <p>User: <%= link_to user.name, user %> </p>
-<% end %>
-</pre>
-
-h3. Set Up the Users Controller, Views, and Routes
-
-Use the Rails generate command to create a "users" controller and a "views/user/show" page.
-
-@$ rails generate controller users show@
-
-Note that "users" is plural when you create the controller.
-
-Modify the file *controllers/users_controller.rb* and add:
-
-<pre>
-before_filter :authenticate_user!
-
-def show
- @user = User.find(params[:id])
-end
-</pre>
-
-Modify the file *views/users/show.html.erb* and add:
-
-<pre>
-<p>User: <%= @user.name %></p>
-</pre>
-
-The file *config/routes.rb* has already been modified to include:
-
-@get "users/show"@
-
-Remove that and change the routes to:
-
-<pre>
-root :to => "home#index"
-devise_for :users
-resources :users, :only => :show
-</pre>
-
-Important note: The @devise_for :users@ route must be placed above @resources :users, :only => :show@.
-
-h3. Add Devise Navigation Links
-
-You will want to add navigation links to the application layout for the Devise sign-up and log-in actions. You'll find a simple example on the "Devise wiki":http://wiki.github.com/plataformatec/devise/adding-menu-items-with-devise-actions-to-your-layout-template.
-
-Create the file *views/devise/menu/_login_items.html.erb* and add:
-
-<pre>
-<% if user_signed_in? %>
- <li>
- <%= link_to('Logout', destroy_user_session_path) %>
- </li>
-<% else %>
- <li>
- <%= link_to('Login', new_user_session_path) %>
- </li>
-<% end %>
-</pre>
-
-Create the file *views/devise/menu/_registration_items.html.erb* and add:
-
-<pre>
-<% if user_signed_in? %>
- <li>
- <%= link_to('Edit account', edit_user_registration_path) %>
- </li>
-<% else %>
- <li>
- <%= link_to('Sign up', new_user_registration_path) %>
- </li>
-<% end %>
-</pre>
-
-Then use these templates in your *layouts/application.html.erb* file, like this:
-
-<pre>
-<ul class="hmenu">
- <%= render 'devise/menu/registration_items' %>
- <%= render 'devise/menu/login_items' %>
-</ul>
-<%= yield %>
-</pre>
-
-Create a *public/stylesheets/application.css* file and add some menu styling to the css (here for a horizontal menu):
-
-<pre>
-ul.hmenu {
- list-style: none;
- margin: 0 0 2em;
- padding: 0;
-}
-
-ul.hmenu li {
- display: inline;
-}
-</pre>
-
-h3. Include Flash Messages
-
-Be sure you have included flash messages in *views/layouts/application.html.erb*, like this:
-
-<pre>
-<ul class="hmenu">
- <%= render 'devise/menu/registration_items' %>
- <%= render 'devise/menu/login_items' %>
-</ul>
-<p style="color: green"><%= notice %></p>
-<p style="color: red"><%= alert %></p>
-<%= yield %>
-</pre>
-
-h2. Create Customized Views for User Registration
-
-Devise provides a controller and views for registering users. It is called the "registerable" module. The controller and views are hidden in the Devise gem so we don't need to create anything. However, because we want our users to provide a name when registering, we will create custom views for creating and editing a user. Our custom views will override the Devise gem defaults.
-
-First, to copy all the default Devise views to your application, run
-
-@rails generate devise:views@
-
-This will generate a set of views in the directory *app/views/devise/*.
-
-Next, modify the views to create and edit users.
-
-Add the following code to each file:
-
-*app/views/devise/registrations/edit.html.erb*
-
-<pre>
- <p><%= f.label :name %><br />
- <%= f.text_field :name %></p>
-</pre>
-
-*app/views/devise/registrations/new.html.erb*
-
-<pre>
- <p><%= f.label :name %><br />
- <%= f.text_field :name %></p>
-</pre>
-
-We do not need to add a controller with methods to create a new user or edit or delete a user. We use the existing "registerable" module from Devise which provides a controller with methods to create, edit or delete a user.
-
-Note that Devise's default behaviour allows any logged-in user to edit or delete his or her own record (but no one else's). When you access the edit page you are editing just your info, and not info of other users.
-
-h2. Test the App
-
-You can check that your app runs properly 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. You should see the default user listed on the home page. When you click on the user's name, you should be required to log in before seeing the user's detail page.
-
-Stop the server with Control-C.
-
-h2. Deploy to Heroku
-
-h3. Set Up Heroku
-
-For your convenience, here are instructions for deploying your app to Heroku. Heroku provides low cost, easily configured Rails application hosting.
-
-To deploy this app to Heroku, you must have a Heroku account. If you need to obtain one, visit "http://heroku.com/":http://heroku.com/ to set up an account.
-
-Make sure the Heroku gem is in your *Gemfile*. If it's not, add it and run
-
-@$ bundle install@
-
-to set up your gems again.
-
-Add your public key immediately after installing the heroku gem so that you can use git to push or clone Heroku app repositories. See "http://docs.heroku.com/heroku-command":http://docs.heroku.com/heroku-command for details.
-
-h3. Create Your Application on Heroku
-
-Use the Heroku create command to create and name your new app.
-
-@$ heroku create _myapp_@
-
-h3. Heroku Add-on for MongoHQ
-
-You can use a Heroku add-on to deploy your app using the MongoHQ service.
-
-To enable the add-on, you can use the Heroku web interface or you can enter the following commands:
-
-@$ heroku addons:add mongohq:free@
-
-You can check that everything has been added correctly by running:
-
-@$ heroku info --app myapp@
-
-h3. Set Up Your Application on Heroku
-
-Push your application to Heroku:
-
-@$ git push heroku master@
-
-Initialize your application database:
-
-@$ heroku rake db:seed@
-
-If you get the error message "failed to connect to any given host:port", you likely failed to set up your *config/application.rb* file to include the MongoHQ connection parameters.
-
-h3. Visit Your Site
-
-Open your Heroku site in your default web browser:
-
-@$ heroku open@
-
-h3. Troubleshooting
-
-If you get errors, you can troubleshoot by reviewing the log files:
-
-@$ heroku logs@
-
-h2. Conclusion
-
-This concludes the tutorial for creating a Ruby on Rails web application that requires Rails 3 and uses Mongoid for data storage and Devise for user management and authentication.
-
-h3. Credits
-
-Daniel Kehoe ("http://danielkehoe.com/":http://danielkehoe.com/) implemented the application and wrote the tutorial.
-
-Was this useful to you? Follow me on Twitter:
-"http://twitter.com/yaxdotcom":http://twitter.com/yaxdotcom
-and tweet some praise. I'd love to know you were helped out by the tutorial.
-
-Any issues? Please create an "Issue":http://github.com/fortuity/rails3-mongoid-devise/issues on GitHub.
-
-
Please sign in to comment.
Something went wrong with that request. Please try again.