Ruby on Rails Basic Tutorial

By Xah Lee. Date: . Last updated: .

This is a basic tutorial of Ruby on Rails.

THIS TUTORIAL IS WORK IN PROGRESS. You should check out other Rails tutorial instead. When this tutorial is robust, this paragraph will be removed.

Rails Install and Intro

Before you start learning Rails, you should clearly understand What's RVM, Gem, Rake, Bundler, RDoc, ri, irb?.

Also, you should understand that “rail” is a command line tool. See: Rails Install and Intro.

starting a Rails project

cd to your home dir, cd ~, then do

rails new xahrails2

sample output:

rails new xahrails2
      create  README.rdoc
      create  Rakefile
      create  .gitignore
      create  Gemfile
      create  app
      create  app/assets/images/rails.png
      create  app/assets/javascripts/application.js
      create  app/assets/stylesheets/application.css
      create  app/controllers/application_controller.rb
      create  app/helpers/application_helper.rb
      create  app/mailers
      create  app/models
      create  app/views/layouts/application.html.erb
      create  app/mailers/.gitkeep
      create  app/models/.gitkeep
      create  config
      create  config/routes.rb
      create  config/application.rb
      create  config/environment.rb
      create  config/environments
      create  config/environments/development.rb
      create  config/environments/production.rb
      create  config/environments/test.rb
      create  config/initializers
      create  config/initializers/backtrace_silencers.rb
      create  config/initializers/inflections.rb
      create  config/initializers/mime_types.rb
      create  config/initializers/secret_token.rb
      create  config/initializers/session_store.rb
      create  config/initializers/wrap_parameters.rb
      create  config/locales
      create  config/locales/en.yml
      create  config/boot.rb
      create  config/database.yml
      create  db
      create  db/seeds.rb
      create  doc
      create  doc/README_FOR_APP
      create  lib
      create  lib/tasks
      create  lib/tasks/.gitkeep
      create  lib/assets
      create  lib/assets/.gitkeep
      create  log
      create  log/.gitkeep
      create  public
      create  public/404.html
      create  public/422.html
      create  public/500.html
      create  public/favicon.ico
      create  public/index.html
      create  public/robots.txt
      create  script
      create  script/rails
      create  test/fixtures
      create  test/fixtures/.gitkeep
      create  test/functional
      create  test/functional/.gitkeep
      create  test/integration
      create  test/integration/.gitkeep
      create  test/unit
      create  test/unit/.gitkeep
      create  test/performance/browsing_test.rb
      create  test/test_helper.rb
      create  tmp/cache
      create  tmp/cache/assets
      create  vendor/assets/javascripts
      create  vendor/assets/javascripts/.gitkeep
      create  vendor/assets/stylesheets
      create  vendor/assets/stylesheets/.gitkeep
      create  vendor/plugins
      create  vendor/plugins/.gitkeep
         run  bundle install
Fetching gem metadata from
Fetching gem metadata from
Using rake (10.0.2)
Using i18n (0.6.1)
Using multi_json (1.4.0)
Using activesupport (3.2.9)
Using builder (3.0.4)
Using activemodel (3.2.9)
Using erubis (2.7.0)
Using journey (1.0.4)
Using rack (1.4.1)
Using rack-cache (1.2)
Using rack-test (0.6.2)
Using hike (1.2.1)
Using tilt (1.3.3)
Using sprockets (2.2.2)
Using actionpack (3.2.9)
Using mime-types (1.19)
Using polyglot (0.3.3)
Using treetop (1.4.12)
Using mail (2.4.4)
Using actionmailer (3.2.9)
Using arel (3.0.2)
Using tzinfo (0.3.35)
Using activerecord (3.2.9)
Using activeresource (3.2.9)
Using bundler (1.2.3)
Using coffee-script-source (1.4.0)
Using execjs (1.4.0)
Using coffee-script (2.2.0)
Using rack-ssl (1.3.2)
Using json (1.7.5)
Using rdoc (3.12)
Using thor (0.16.0)
Using railties (3.2.9)
Using coffee-rails (3.2.2)
Using jquery-rails (2.1.4)
Using rails (3.2.9)
Using sass (3.2.3)
Using sass-rails (3.2.5)
Using sqlite3 (1.3.6)
Using uglifier (1.3.0)
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.

this will create a dir named xahrails2 in current dir.

In the dir, it'll contain these dirs:

app/Your main app code. Including all code for {models, views, controllers}
app/assetsYour site's {image files, CSS, JavaScript, …} files.
config/Config files. ➢ for example: routes, database setup, ….
config.ruConfig for Rack-based servers.
db/Database files
doc/Docs of your app
GemfileDependency Spec for Ruby libs required by Rails for this app.
Gemfile.lockContains exact version numbers.
.gitignoreA pattern spec for the git version control. You don't need it if you are not using git. 〔➤see git Tutorial
lib/Extra modules for your app.
log/Your app's log files
public/Public, static, files.
RakefileFor the “ruby make” rake program. Your app's rake file should be at lib/tasks.
README.rdocShort description of your app.
script/Rails script that starts your app. And for other scripts.
test/Unit Tests code and other testing.
tmp/temp files. (➢ for example: cache, pid, session, …)
vendor/Dir for third-party libs for your app.

starting server

To start Rails server, cd into to your Rails project dir first, then run:

cd your_rail_project_dir

rails server

Remember, you must be in your Rails project dir.

Sample output:

◆ rails server
=> Booting WEBrick
=> Rails 3.2.9 application starting in development on
=> Call with -d to detach
=> Ctrl-C to shutdown server
[2012-12-08 14:29:04] INFO  WEBrick 1.3.1
[2012-12-08 14:29:04] INFO  ruby 1.9.3 (2012-11-10) [i686-linux]
[2012-12-08 14:29:04] INFO  WEBrick::HTTPServer#start: pid=29365 port=3000

Note: Rails server will hog your terminal. So, either start in a new terminal, or you can type 【Ctrl+z】 to send it to the background. To bring it back, type fg.

By default, the server starts listening to port 3000. Go to http://localhost:3000/ in your browser to visit.

The default server is a simple one written in Ruby, named WEBrick. You can see its doc at

You can use shell ps to check if the server is running. Example:

◆ ps -ef | grep ruby
xah      29365  2009  0 14:29 pts/1    00:00:03 /home/xah/.rvm/rubies/ruby-1.9.3-p327/bin/ruby script/rails server
xah      29402 26605  0 14:37 pts/2    00:00:00 grep --color=auto ruby
ruby on rails start screen 2012-12-08
Rails start screen.

How to start Rails server?

cd to your Rails project dir, then rails server

How to stop Rails server?

In the terminal where Rails server started, type 【Ctrl+c】 in the terminal. Here's sample output:

◆ fg
rails server
^C[2012-12-08 16:36:48] INFO  going to shutdown ...
[2012-12-08 16:36:48] INFO  WEBrick::HTTPServer#start done.

Or just kill, first sudo ps -ef | grep 'rails server' then kill -9 pid.

◆ xah@xah-VB3◆ 2012-12-09 11:47 ◆ ~/xahrailplay
◆ rails generate scaffold User name:string email:string
      invoke  active_record
      create    db/migrate/20121209194721_create_users.rb
      create    app/models/user.rb
      invoke    test_unit
      create      test/unit/user_test.rb
      create      test/fixtures/users.yml
      invoke  resource_route
       route    resources :users
      invoke  scaffold_controller
      create    app/controllers/users_controller.rb
      invoke    erb
      create      app/views/users
      create      app/views/users/index.html.erb
      create      app/views/users/edit.html.erb
      create      app/views/users/show.html.erb
      create      app/views/users/new.html.erb
      create      app/views/users/_form.html.erb
      invoke    test_unit
      create      test/functional/users_controller_test.rb
      invoke    helper
      create      app/helpers/users_helper.rb
      invoke      test_unit
      create        test/unit/helpers/users_helper_test.rb
      invoke  assets
      invoke    coffee
      create      app/assets/javascripts/
      invoke    scss
      create      app/assets/stylesheets/users.css.scss
      invoke  scss
      create    app/assets/stylesheets/scaffolds.css.scss
◆ xah@xah-VB3◆ 2012-12-09 11:47 ◆ ~/xahrailplay
◆ xah@xah-VB3◆ 2012-12-09 11:47 ◆ ~/xahrailplay
◆ bundle exec rake db:migrate
==  CreateUsers: migrating ====================================================
-- create_table(:users)
   -> 0.0018s
==  CreateUsers: migrated (0.0118s) ===========================================

◆ xah@xah-VB3◆ 2012-12-09 11:50 ◆ ~/xahrailplay
◆ xah@xah-VB3◆ 2012-12-09 11:50 ◆ ~/xahrailplay
◆ rails generate scaffold Micropost content:string user_id:integer
      invoke  active_record
      create    db/migrate/20121209210317_create_microposts.rb
      create    app/models/micropost.rb
      invoke    test_unit
      create      test/unit/micropost_test.rb
      create      test/fixtures/microposts.yml
      invoke  resource_route
       route    resources :microposts
      invoke  scaffold_controller
      create    app/controllers/microposts_controller.rb
      invoke    erb
      create      app/views/microposts
      create      app/views/microposts/index.html.erb
      create      app/views/microposts/edit.html.erb
      create      app/views/microposts/show.html.erb
      create      app/views/microposts/new.html.erb
      create      app/views/microposts/_form.html.erb
      invoke    test_unit
      create      test/functional/microposts_controller_test.rb
      invoke    helper
      create      app/helpers/microposts_helper.rb
      invoke      test_unit
      create        test/unit/helpers/microposts_helper_test.rb
      invoke  assets
      invoke    coffee
      create      app/assets/javascripts/
      invoke    scss
      create      app/assets/stylesheets/microposts.css.scss
      invoke  scss
   identical    app/assets/stylesheets/scaffolds.css.scss
◆ xah@xah-VB3◆ 2012-12-09 13:03 ◆ ~/xahrailplay