Ruby on Rails Guides

https://guides.rubyonrails.org/
Admin
Comprehensive guides for Ruby on Rails, covering installation, core concepts like Active Record,...
Tokens:1,060,143
Snippets:8,335
Trust Score:9.9
Update:23 hours ago
Show doc for...
Tokens:
Raw
### Run importmap:install task

Source: https://guides.rubyonrails.org/working_with_javascript_in_rails.html

Installs the import map configuration and setup for the application. Run after adding the gem.

```bash
$ bin/rails importmap:install
```

--------------------------------

### Deploy with bin/kamal deploy

Source: https://guides.rubyonrails.org/sign_up_and_settings.html

Run this command to build a new container and deploy the application to the production server. Requires prior Kamal setup as described in the Getting Started Guide.

```bash
$ bin/kamal deploy
```

--------------------------------

### Set up development environment using Dev Container CLI

Source: https://guides.rubyonrails.org/contributing_to_ruby_on_rails.html

Install the Dev Container CLI globally, then start and enter a dev container for the Rails repository. Requires npm and Docker.

```shell
$ npm install -g @devcontainers/cli
$ cd rails
$ devcontainer up --workspace-folder .
$ devcontainer exec --workspace-folder . bash
```

--------------------------------

### Generate translated Rails guides (e.g., it-IT)

Source: https://guides.rubyonrails.org/contributing_to_ruby_on_rails.html

Install guides dependencies and generate HTML guides for a specific language. Run from the guides directory. The Redcarpet Gem doesn't work with JRuby.

```shell
$ BUNDLE_ONLY=default:doc bundle install
$ cd guides/
$ BUNDLE_ONLY=default:doc bundle exec rake guides:generate:html GUIDES_LANGUAGE=it-IT
```

--------------------------------

### Install Rails 3 with gem install

Source: https://guides.rubyonrails.org/3_0_release_notes.html

Command to install Rails 3. Use sudo if your setup requires it.

```bash
# Use sudo if your setup requires it
$ gem install rails
```

--------------------------------

### Puma Rack handler run method

Source: https://guides.rubyonrails.org/initialization.html

Example implementation of server.run for Puma. Configures the launcher, handles interrupts gracefully, and starts the server.

```ruby
module Rack
  module Handler
    module Puma
      # ...
      def self.run(app, options = {})
        conf = self.config(app, options)

        log_writer = options.delete(:Silent) ? ::Puma::LogWriter.strings : ::Puma::LogWriter.stdio

        launcher = ::Puma::Launcher.new(conf, log_writer: log_writer, events: @events)

        yield launcher if block_given?
        begin
          launcher.run
        rescue Interrupt
          puts "* Gracefully stopping, waiting for requests to finish"
          launcher.stop
          puts "* Goodbye!"
        end
      end
      # ...
    end
  end
end
```

--------------------------------

### Start a Homebrew service

Source: https://guides.rubyonrails.org/development_dependencies_install.html

Start a specific service, replacing 'mysql' with the name of the service you want to start.

```bash
$ brew services start mysql
```

--------------------------------

### Run Rack app with config.ru and puma

Source: https://guides.rubyonrails.org/rails_on_rack.html

Create a `config.ru` file with a lambda-based Rack app, install Puma, and start the server. The app will be available at http://localhost:9292.

```bash
$ cat > config.ru << APP
rack_app = lambda do |env|
  [200, { "content-type" => "text/plain" }, ["Hello World"]]
end
run rack_app
APP
$ gem install puma
$ puma
```

--------------------------------

### Start Solid Queue jobs

Source: https://guides.rubyonrails.org/active_job_basics.html

Start the queue and begin processing jobs with bin/jobs start.

```bash
$ bin/jobs start
```

--------------------------------

### Sample template.rb with Devise setup

Source: https://guides.rubyonrails.org/generators.html

A template that asks to install Devise, names the user model, runs generators and migrations after bundle, and commits changes. Uses Rails Template API methods like yes?, ask, after_bundle, generate, rails_command, and git.

```ruby
# template.rb
if yes?("Would you like to install Devise?")
  gem "devise"
  devise_model = ask("What would you like the user model to be called?", default: "User")
end

after_bundle do
  if devise_model
    generate "devise:install"
    generate "devise", devise_model
    rails_command "db:migrate"
  end

  git add: ".", commit: %(-m 'Initial commit')
end
```

--------------------------------

### Make requests with app.get

Source: https://guides.rubyonrails.org/command_line.html

Shows how to use the app object to make a GET request without starting a server. The Host header must be passed because the Rack client defaults to www.example.com.

```ruby
my-app(dev)> app.get "/", headers: { "Host" => "localhost" }
Started GET "/" for 127.0.0.1 at 2025-08-11 11:11:34 -0500
...

my-app(dev)> app.response.status
=> 200
```

--------------------------------

### Option section style with example

Source: https://guides.rubyonrails.org/api_documentation_guidelines.html

Alternative approach for providing additional detail and examples. Example from ActiveSupport::MessageEncryptor#encrypt_and_sign showing options with descriptions and usage example.

```ruby
# ==== Options
#
# [+:expires_at+]
#   The datetime at which the message expires. After this datetime,
#   verification of the message will fail.
#
#     message = encryptor.encrypt_and_sign("hello", expires_at: Time.now.tomorrow)
#     encryptor.decrypt_and_verify(message) # => "hello"
#     # 24 hours later...
#     encryptor.decrypt_and_verify(message) # => nil
```

--------------------------------

### Example config/locales directory structure

Source: https://guides.rubyonrails.org/i18n.html

An example hierarchy for organizing locale files by defaults, models, and views. This is only an example; choose a structure that fits your application.

```text
|-defaults
|---es.yml
|---en.yml
|-models
|---book
|-----es.yml
|-----en.yml
|-views
|---defaults
|-----es.yml
|-----en.yml
|---books
|-----es.yml
|-----en.yml
|---users
|-----es.yml
|-----en.yml
|---navigation
|-----es.yml
|-----en.yml
```

--------------------------------

### Run bin/kamal setup for first deployment

Source: https://guides.rubyonrails.org/getting_started.html

Sets up your server and deploys your application for the first time. After this, your app is live and accessible via the server's IP.

```bash
$ bin/kamal setup

```

--------------------------------

### Set up test database with cd and bin/rails db:create

Source: https://guides.rubyonrails.org/plugins.html

Navigate to the test/dummy directory and create the test database. This is required before running the plugin's tests.

```shell
$ cd test/dummy
$ bin/rails db:create
```

--------------------------------

### POST request with Basic Authentication header

Source: https://guides.rubyonrails.org/testing.html

Example of adding authorization to a POST request using Basic Authentication credentials. Required if following the Basic Authentication section in the getting started guide.

```ruby
post articles_url, params: { article: { body: "Rails is awesome!", title: "Hello Rails" } }, headers: { Authorization: ActionController::HttpAuthentication::Basic.encode_credentials("dhh", "secret") }
```

--------------------------------

### Generate all guides (HTML)

Source: https://guides.rubyonrails.org/ruby_on_rails_guides_guidelines.html

Commands to generate all guides in HTML format. The first command is the default, the second is an explicit HTML variant. Output is placed in the ./output directory.

```bash
$ bundle exec rake guides:generate
```

```bash
$ bundle exec rake guides:generate:html
```

--------------------------------

### Install or update Bundler

Source: https://guides.rubyonrails.org/ruby_on_rails_guides_guidelines.html

Commands to install or update the Bundler gem, required before generating guides.

```bash
gem install bundler
```

```bash
gem update bundler
```

--------------------------------

### Generate a single guide with ONLY

Source: https://guides.rubyonrails.org/ruby_on_rails_guides_guidelines.html

Commands to process only a specific guide file (my_guide.md) using the ONLY environment variable. The touch command creates the file if it doesn't exist.

```bash
$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide
```

--------------------------------

### Install Active Storage and Run Migrations

Source: https://guides.rubyonrails.org/active_storage_overview.html

Run these commands to install Active Storage and create the required tables (active_storage_blobs, active_storage_attachments, active_storage_variant_records).

```bash
$ bin/rails active_storage:install
$ bin/rails db:migrate
```

--------------------------------

### GET request to my_action.csv

Source: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html

Example HTTP GET request to the action, demonstrating the Content-Type change.

```ruby
get("my_action.csv")
```

--------------------------------

### Install Action Mailbox

Source: https://guides.rubyonrails.org/action_mailbox_basics.html

Run the installer to create application_mailbox.rb and copy migrations.

```bash
$ bin/rails action_mailbox:install
```

--------------------------------

### Set up development environment using Dev Container with Podman

Source: https://guides.rubyonrails.org/contributing_to_ruby_on_rails.html

Initialize and start a Podman machine, then bring up the dev container. Run the first two commands in one terminal, then the next two in a separate terminal.

```shell
$ podman machine init
$ podman machine start
$ tools/devcontainer up
```

```shell
$ tools/devcontainer run-user-commands
$ tools/devcontainer sh
```

--------------------------------

### GET request with HTTP_REFERER header

Source: https://guides.rubyonrails.org/testing.html

Example of calling the `:show` action via a `get` request for the first Article, passing an `HTTP_REFERER` header.

```ruby
get article_url(Article.first), headers: { "HTTP_REFERER" => "http://example.com/home" }
```

--------------------------------

### List available Homebrew services

Source: https://guides.rubyonrails.org/development_dependencies_install.html

List all available services that can be started with Homebrew services.

```bash
$ brew services list
```

--------------------------------

### Create the application database with bin/rails db:create

Source: https://guides.rubyonrails.org/getting_started.html

Run this command in the `store` directory to create the application's database. This is the first step before starting the Rails server.

```bash
$ bin/rails db:create
```

--------------------------------

### number_to_human examples

Source: https://guides.rubyonrails.org/action_view_helpers.html

Pretty prints (formats and approximates) a number so it is more readable by users; useful for numbers that can get very large. The examples show output for 1234 and 1234567.

```ruby
number_to_human(1234)    # => 1.23 Thousand
number_to_human(1234567) # => 1.23 Million
```

--------------------------------

### Date#beginning_of_week and Date#end_of_week with optional start day

Source: https://guides.rubyonrails.org/active_support_core_extensions.html

Shows how to get the start and end of the week for a given date. Weeks default to Monday, but you can pass an argument like :sunday to change the start day. The output comments show the resulting dates.

```ruby
d = Date.new(2010, 5, 8)     # => Sat, 08 May 2010
d.beginning_of_week          # => Mon, 03 May 2010
d.beginning_of_week(:sunday) # => Sun, 02 May 2010
d.end_of_week                # => Sun, 09 May 2010
d.end_of_week(:sunday)       # => Sat, 08 May 2010
```

--------------------------------

### belongs_to :primary_key option example

Source: https://guides.rubyonrails.org/association_basics.html

Configures a custom primary key 'guid' on the users table and references it as a foreign key in the todos table. When @user.todos.create is executed, the @todo record's user_id is set to the guid value of @user.

```ruby
class User < ApplicationRecord
  self.primary_key = "guid" # Sets the primary key to guid instead of id
end

class Todo < ApplicationRecord
  belongs_to :user, primary_key: "guid" # References the guid column in users table
end
```

--------------------------------

### Start Rails Server with Rails::Server.new

Source: https://guides.rubyonrails.org/rails_on_rack.html

Shows how bin/rails server instantiates a Rails::Server object and starts the web server. The code requires the application path, changes to the application root, and starts the server.

```ruby
Rails::Server.new.tap do |server|
  require APP_PATH
  Dir.chdir(Rails.application.root)
  server.start
end
```

--------------------------------

### Clashing named routes with resources and explicit route

Source: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html

Rails 4.0 raises ArgumentError when a resources route clashes with an explicitly defined named route. This example shows a resources :examples route and a get route both named example_path.

```ruby
resources :examples
get "clashing/:id" => "test#example", as: :example
```

--------------------------------

### Install Action Text

Source: https://guides.rubyonrails.org/getting_started.html

Run the Action Text installer, install dependencies, and migrate the database. Restart the Rails server afterward to load new features.

```bash
$ bin/rails action_text:install
$ bundle install
$ bin/rails db:migrate
```

--------------------------------

### User model with has_one :profile

Source: https://guides.rubyonrails.org/active_support_core_extensions.html

Initial model setup showing a User with a profile association, used as the basis for delegation examples.

```ruby
class User < ApplicationRecord
  has_one :profile
end
```

--------------------------------

### Count errors with errors.size

Source: https://guides.rubyonrails.org/active_record_validations.html

Shows how to use errors.size to get the total number of errors for an object, with examples for invalid and valid objects.

```ruby
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors.size
=> 2

irb> person = Person.new(name: "Andrea", email: "andrea@example.com")
irb> person.valid?
=> true
irb> person.errors.size
=> 0
```

--------------------------------

### Start Rails server with bin/rails server

Source: https://guides.rubyonrails.org/command_line.html

Launches the Puma web server bundled with Rails. The output shows the server booting in development mode, listening on port 3000. Use Ctrl-C to stop.

```bash
$ cd my_app
$ bin/rails server
=> Booting Puma
=> Rails 8.1.0 application starting in development
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 6.4.0 (ruby 3.1.3-p185) ("The Eagle of Durango")
*  Min threads: 3
*  Max threads: 3
*  Environment: development
*          PID: 5295
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop
```

--------------------------------

### Real example from Active Support en.yml

Source: https://guides.rubyonrails.org/i18n.html

Shows date format translations from the Active Support en.yml file.

```yaml
en:
  date:
    formats:
      default: "%Y-%m-%d"
      short: "%b %d"
      long: "%B %d, %Y"
```

--------------------------------

### find_each with start and finish options

Source: https://guides.rubyonrails.org/active_record_querying.html

Configures the last ID of the sequence. Example sends newsletters to customers with primary key from 2000 to 9999.

```ruby
Customer.find_each(start: 2000, finish: 9999) do |customer|
  NewsMailer.weekly(customer).deliver_now
end
```

--------------------------------

### Hstore: Usage examples

Source: https://guides.rubyonrails.org/active_record_postgresql.html

Shows creating a profile with hstore settings, updating settings, and querying using the -> operator.

```ruby
irb> Profile.create(settings: { "color" => "blue", "resolution" => "800x600" })

irb> profile = Profile.first
irb> profile.settings
=> {"color"=>"blue", "resolution"=>"800x600"}

irb> profile.settings = {"color" => "yellow", "resolution" => "1280x1024"}
irb> profile.save!

irb> Profile.where("settings->'color' = ?", "yellow")
=> #<ActiveRecord::Relation [#<Profile id: 1, settings: {"color"=>"yellow", "resolution"=>"1280x1024"}>]>
```

--------------------------------

### Average order subtotal

Source: https://guides.rubyonrails.org/active_record_querying.html

Calls Order.average("subtotal") to get the average of the subtotal field. The example shows the result 3.14159265.

```ruby
Order.average("subtotal")
# => 3.14159265
```

--------------------------------

### Example: to_s with collection

Source: https://guides.rubyonrails.org/api_documentation_guidelines.html

Shows a short example that follows a paragraph without an explicit 'Examples' label. Demonstrates the output of calling to_s on a collection.

```ruby
# Converts a collection of elements into a formatted string by
# calling +to_s+ on all elements and joining them.
#
#   Blog.all.to_fs # => "First PostSecond PostThird Post"

```

--------------------------------

### Validate generated HTML

Source: https://guides.rubyonrails.org/ruby_on_rails_guides_guidelines.html

Command to validate the generated HTML guides. Note that titles get an ID generated from their content, which often leads to duplicates.

```bash
$ bundle exec rake guides:validate
```

--------------------------------

### Rackup::Server#wrapped_app method

Source: https://guides.rubyonrails.org/initialization.html

Memoizes the wrapped app by calling build_app with the app. This is called during server start and later to get the Rack app.

```ruby
module Rackup
  class Server
    def wrapped_app
      @wrapped_app ||= build_app app
    end
  end
end
```

--------------------------------

### Rackup::Server#start method

Source: https://guides.rubyonrails.org/initialization.html

Defines the start method for Rackup::Server. It handles warnings, includes, requires, debug mode, pid file, profiling, daemonization, and traps INT signals to shutdown the server. Finally runs the server with wrapped_app.

```ruby
module Rackup
  class Server
    def start(&block)
      if options[:warn]
        $-w = true
      end

      if includes = options[:include]
        $LOAD_PATH.unshift(*includes)
      end

      Array(options[:require]).each do |library|
        require library
      end

      if options[:debug]
        $DEBUG = true
        require "pp"
        p options[:server]
        pp wrapped_app
        pp app
      end

      check_pid! if options[:pid]

      # Touch the wrapped app, so that the config.ru is loaded before
      # daemonization (i.e. before chdir, etc).
      handle_profiling(options[:heapfile], options[:profile_mode], options[:profile_file]) do
        wrapped_app
      end

      daemonize_app if options[:daemonize]

      write_pid if options[:pid]

      trap(:INT) do
        if server.respond_to?(:shutdown)
          server.shutdown
        else
          exit
        end
      end

      server.run(wrapped_app, **options, &block)
    end
  end
end
```

--------------------------------

### Get help for a generator

Source: https://guides.rubyonrails.org/generators.html

Shows the output of bin/rails generate scaffold --help, which provides detailed usage instructions and examples for the scaffold generator.

```shell
$ bin/rails generate scaffold --help
Usage:
  bin/rails generate scaffold NAME [field[:type][:index] field[:type][:index]] [options]
...
Description:
    Scaffolds an entire resource, from model and migration to controller and
    views, along with a full test suite. The resource is ready to use as a
    starting point for your RESTful, resource-oriented application.
...
Examples:
    `bin/rails generate scaffold post`
    `bin/rails generate scaffold post title:string body:text published:boolean`
    `bin/rails generate scaffold purchase amount:decimal tracking_id:integer:uniq`
    `bin/rails generate scaffold user email:uniq password:digest`
...

```

--------------------------------

### Counter variable example with index.html.erb and _product.html.erb

Source: https://guides.rubyonrails.org/action_view_overview.html

Shows how to use the counter variable in a partial rendered by a collection. The counter starts at 0 and increments for each rendered partial.

```erb
<%# index.html.erb %>
<%= render partial: "product", collection: @products %>
```

```erb
<%# _product.html.erb %>
<%= product_counter %> # 0 for the first product, 1 for the second product...
```

--------------------------------

### to_param used in routing

Source: https://guides.rubyonrails.org/active_support_core_extensions.html

The Rails routing system calls to_param on models to get a value for the :id placeholder. This example shows the resulting URL path.

```ruby
user_path(@user) # => "/users/357-john-smith"
```

--------------------------------

### Default Solid Queue configuration in config/queue.yml

Source: https://guides.rubyonrails.org/active_job_basics.html

Example default configuration for Solid Queue. Run bin/jobs start to start the supervisor, which forks and manages workers and dispatchers according to this file. Configuration is optional; if omitted, Solid Queue runs with one dispatcher and one worker with default settings.

```yaml
# config/queue.yml
default: &default
  dispatchers:
    - polling_interval: 1
      batch_size: 500
  workers:
    - queues: "*"
      threads: 3
      processes: <%= ENV.fetch("JOB_CONCURRENCY", 1) %>
      polling_interval: 0.1
```

--------------------------------

### Install all dependencies on FreeBSD

Source: https://guides.rubyonrails.org/development_dependencies_install.html

Use these commands to install all required development dependencies on FreeBSD. The second command is commented out and suggests using portmaster for redis.

```bash
$ sudo pkg install sqlite3 mysql80-client mysql80-server postgresql11-client postgresql11-server memcached imagemagick6 ffmpeg mupdf yarn libxml2 vips poppler-utils
# portmaster databases/redis
```

--------------------------------

### after_bundle: run commands after bundling

Source: https://guides.rubyonrails.org/generators.html

Registers a callback to run after gems are bundled. Example installs TailwindCSS and Devise. Callbacks execute even if --skip-bundle is passed.

```ruby
# Install gems
after_bundle do
  # Install TailwindCSS
  rails_command "tailwindcss:install"

  # Install Devise
  generate "devise:install"
end
```

--------------------------------

### file helper: create app/components/foo.rb

Source: https://guides.rubyonrails.org/generators.html

Creates a file at a relative path from Rails.root, creating all needed directories. The example creates app/components/foo.rb with a Foo class.

```ruby
file "app/components/foo.rb", <<-CODE
  class Foo
  end
CODE
```

--------------------------------

### Create a Rails app and list generators

Source: https://guides.rubyonrails.org/generators.html

Shows how to create a new Rails application and then list all available generators using bin/rails generate. The output includes usage instructions and a list of generators grouped by namespace.

```shell
$ rails new myapp
$ cd myapp
$ bin/rails generate
Usage:
  bin/rails generate GENERATOR [args] [options]

General options:
  -h, [--help]     # Print generator's options and usage
  -p, [--pretend]  # Run but do not make any changes
  -f, [--force]    # Overwrite files that already exist
  -s, [--skip]     # Skip files that already exist
  -q, [--quiet]    # Suppress status output

Please choose a generator below.

Rails:
  application_record
  authentication
  benchmark
  channel
  controller
  generator
  ...
SolidQueue:
  solid_queue:install

Stimulus:
  stimulus

TestUnit:
  test_unit:authentication
  test_unit:channel
  ...

```

--------------------------------

### git: run git commands from template

Source: https://guides.rubyonrails.org/generators.html

Runs any git command with the git helper. Example initializes a repository, stages all changes, and commits.

```ruby
git :init
git add: "."
git commit: "-a -m 'Initial commit'"
```

--------------------------------

### Run tests at a specific line number

Source: https://guides.rubyonrails.org/contributing_to_ruby_on_rails.html

Runs tests starting at a specific line number in a test file. Example runs the test at line 69 in asset_debugging_test.rb.

```shell
$ cd railties
$ bin/test test/application/asset_debugging_test.rb:69
```

--------------------------------

### Use concerns in namespace blocks

Source: https://guides.rubyonrails.org/routing.html

Calls concerns inside namespace blocks to get the same result as using them in resources. This example uses namespace :messages and namespace :articles.

```ruby
namespace :messages do
  concerns :commentable
end

namespace :articles do
  concerns :commentable
  concerns :image_attachable
end
```

--------------------------------

### Example Channel Classes (ChatChannel and AppearanceChannel)

Source: https://guides.rubyonrails.org/action_cable_overview.html

Shows how to define your own channel classes that inherit from ApplicationCable::Channel. A consumer can subscribe to either or both.

```ruby
# app/channels/chat_channel.rb
class ChatChannel < ApplicationCable::Channel
end
```

```ruby
# app/channels/appearance_channel.rb
class AppearanceChannel < ApplicationCable::Channel
end
```

--------------------------------

### Example: Bash rails new

Source: https://guides.rubyonrails.org/api_documentation_guidelines.html

Shows how to document command-line examples with '$' prefix and no prefix for output.

```bash
# Run the following command:
#   $ bin/rails new zomg
#   ...

```

--------------------------------

### String#truncate with :separator option

Source: https://guides.rubyonrails.org/active_support_core_extensions.html

Pass a :separator to truncate the string at a natural break. The separator can be a string or a regexp. In the examples, 'dear' gets cut first, but the :separator prevents it.

```Ruby
"Oh dear! Oh dear! I shall be late!".truncate(18)
# => "Oh dear! Oh dea..."
"Oh dear! Oh dear! I shall be late!".truncate(18, separator: " ")
# => "Oh dear! Oh..."
```

```Ruby
"Oh dear! Oh dear! I shall be late!".truncate(18, separator: /\s/)
# => "Oh dear! Oh..."
```
Tokens:
Raw