123456789_123456789_123456789_123456789_123456789_

DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.

Configuring Rails Applications

This guide covers the configuration and initialization features available to Rails applications.

After reading this guide, you will know:

Locations for Initialization Code

Rails offers four standard spots to place initialization code:

Running Code Before Rails

In the rare event that your application needs to run some code before Rails itself is loaded, put it above the call to require "rails/all" in config/application.rb.

Configuring Rails Components

In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The configuration file config/application.rb and environment-specific configuration files (such as config/environments/production.rb) allow you to specify the various settings that you want to pass down to all of the components.

For example, you could add this setting to config/application.rb file:

config.time_zone = 'Central Time (US & Canada)'

This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same config object in config/application.rb:

config.active_record.schema_format = :ruby

Rails will use that particular setting to configure Active Record.

Rails General Configuration

These configuration methods are to be called on a ::Rails::Railtie object, such as a subclass of ::Rails::Engine or ::Rails::Application.

Configuring Assets

Configuring Generators

Rails allows you to alter what generators are used with the config.generators method. This method takes a block:

config.generators do |g|
  g.orm :active_record
  g.test_framework :test_unit
end

The full set of methods that can be used in this block are as follows:

Configuring Middleware

Every Rails application comes with a standard set of middleware which it uses in this order in the development environment:

Besides these usual middleware, you can add your own by using the config.middleware.use method:

config.middleware.use Magical::Unicorns

This will put the Magical::Unicorns middleware on the end of the stack. You can use insert_before if you wish to add a middleware before another.

config.middleware.insert_before Rack::Head, Magical::Unicorns

Or you can insert a middleware to exact position by using indexes. For example, if you want to insert Magical::Unicorns middleware on top of the stack, you can do it, like so:

config.middleware.insert_before 0, Magical::Unicorns

There's also insert_after which will insert a middleware after another:

config.middleware.insert_after Rack::Head, Magical::Unicorns

Middlewares can also be completely swapped out and replaced with others:

config.middleware.swap ActionController::Failsafe, Lifo::Failsafe

Middlewares can be moved from one place to another:

config.middleware.move_before ActionDispatch::Flash, Magical::Unicorns

This will move the Magical::Unicorns middleware before ::ActionDispatch::Flash. You can also move it after:

config.middleware.move_after ActionDispatch::Flash, Magical::Unicorns

They can also be removed from the stack completely:

config.middleware.delete Rack::MethodOverride

Configuring i18n

All these configuration options are delegated to the I18n library.

Configuring Active Model

Configuring Active Record

config.active_record includes a variety of configuration options:

The MySQL adapter adds one additional configuration option:

The PostgreSQL adapter adds one additional configuration option:

The schema dumper adds two additional configuration options:

Configuring Action Controller

config.action_controller includes a number of configuration settings:

Configuring Action Dispatch

Configuring Action View

config.action_view includes a small number of configuration settings:

Configuring Action Mailbox

config.action_mailbox provides the following configuration options:

Configuring Action Mailer

There are a number of settings available on config.action_mailer:

Configuring Active Support

There are a few configuration options available in Active Support:

Configuring Active Job

config.active_job provides the following configuration options:

Configuring Action Cable

You can find more detailed configuration options in the Action Cable Overview.

Configuring Active Storage

config.active_storage provides the following configuration options:

Results of config.load_defaults

config.load_defaults sets new defaults up to and including the version passed. Such that passing, say, 6.0 also gets the new defaults from every version before it.

For '6.1', defaults from previous versions below and:

For '6.0', defaults from previous versions below and:

For '5.2', defaults from previous versions below and:

For '5.1', defaults from previous versions below and:

For '5.0', baseline defaults from below and:

Baseline defaults:

Configuring a Database

Just about every Rails application will interact with a database. You can connect to the database by setting an environment variable ENV['DATABASE_URL'] or by using a configuration file called config/database.yml.

Using the config/database.yml file you can specify all the information needed to access your database:

development:
  adapter: postgresql
  database: blog_development
  pool: 5

This will connect to the database named blog_development using the postgresql adapter. This same information can be stored in a URL and provided via an environment variable like this:

ENV['DATABASE_URL'] # => "postgresql://localhost/blog_development?pool=5"

The config/database.yml file contains sections for three different environments in which Rails can run by default:

If you wish, you can manually specify a URL inside of your config/database.yml

development:
  url: postgresql://localhost/blog_development?pool=5

The config/database.yml file can contain ERB tags <%= %>. Anything in the tags will be evaluated as Ruby code. You can use this to pull out data from an environment variable or to perform calculations to generate the needed connection information.

TIP: You don't have to update the database configurations manually. If you look at the options of the application generator, you will see that one of the options is named --database. This option allows you to choose an adapter from a list of the most used relational databases. You can even run the generator repeatedly: cd .. && rails new blog --database=mysql. When you confirm the overwriting of the config/database.yml file, your application will be configured for MySQL instead of SQLite. Detailed examples of the common database connections are below.

Connection Preference

Since there are two ways to configure your connection (using config/database.yml or using an environment variable) it is important to understand how they can interact.

If you have an empty config/database.yml file but your ENV['DATABASE_URL'] is present, then Rails will connect to the database via your environment variable:

$ cat config/database.yml

$ echo $DATABASE_URL
postgresql://localhost/my_database

If you have a config/database.yml but no ENV['DATABASE_URL'] then this file will be used to connect to your database:

$ cat config/database.yml
development:
  adapter: postgresql
  database: my_database
  host: localhost

$ echo $DATABASE_URL

If you have both config/database.yml and ENV['DATABASE_URL'] set then Rails will merge the configuration together. To better understand this we must see some examples.

When duplicate connection information is provided the environment variable will take precedence:

$ cat config/database.yml
development:
  adapter: sqlite3
  database: NOT_my_database
  host: localhost

$ echo $DATABASE_URL
postgresql://localhost/my_database

$ bin/rails runner 'puts ActiveRecord::Base.configurations'
#<ActiveRecord::DatabaseConfigurations:0x00007fd50e209a28>

$ bin/rails runner 'puts ActiveRecord::Base.configurations.inspect'
#<ActiveRecord::DatabaseConfigurations:0x00007fc8eab02880 @configurations=[
  #<ActiveRecord::DatabaseConfigurations::UrlConfig:0x00007fc8eab020b0
    @env_name="development", @spec_name="primary",
    @config={"adapter"=>"postgresql", "database"=>"my_database", "host"=>"localhost"}
    @url="postgresql://localhost/my_database">
  ]

Here the adapter, host, and database match the information in ENV['DATABASE_URL'].

If non-duplicate information is provided you will get all unique values, environment variable still takes precedence in cases of any conflicts.

$ cat config/database.yml
development:
  adapter: sqlite3
  pool: 5

$ echo $DATABASE_URL
postgresql://localhost/my_database

$ bin/rails runner 'puts ActiveRecord::Base.configurations'
#<ActiveRecord::DatabaseConfigurations:0x00007fd50e209a28>

$ bin/rails runner 'puts ActiveRecord::Base.configurations.inspect'
#<ActiveRecord::DatabaseConfigurations:0x00007fc8eab02880 @configurations=[
  #<ActiveRecord::DatabaseConfigurations::UrlConfig:0x00007fc8eab020b0
    @env_name="development", @spec_name="primary",
    @config={"adapter"=>"postgresql", "database"=>"my_database", "host"=>"localhost", "pool"=>5}
    @url="postgresql://localhost/my_database">
  ]

Since pool is not in the ENV['DATABASE_URL'] provided connection information its information is merged in. Since adapter is duplicate, the ENV['DATABASE_URL'] connection information wins.

The only way to explicitly not use the connection information in ENV['DATABASE_URL'] is to specify an explicit URL connection using the "url" sub key:

$ cat config/database.yml
development:
  url: sqlite3:NOT_my_database

$ echo $DATABASE_URL
postgresql://localhost/my_database

$ bin/rails runner 'puts ActiveRecord::Base.configurations'
#<ActiveRecord::DatabaseConfigurations:0x00007fd50e209a28>

$ bin/rails runner 'puts ActiveRecord::Base.configurations.inspect'
#<ActiveRecord::DatabaseConfigurations:0x00007fc8eab02880 @configurations=[
  #<ActiveRecord::DatabaseConfigurations::UrlConfig:0x00007fc8eab020b0
    @env_name="development", @spec_name="primary",
    @config={"adapter"=>"sqlite3", "database"=>"NOT_my_database"}
    @url="sqlite3:NOT_my_database">
  ]

Here the connection information in ENV['DATABASE_URL'] is ignored, note the different adapter and database name.

Since it is possible to embed ERB in your config/database.yml it is best practice to explicitly show you are using the ENV['DATABASE_URL'] to connect to your database. This is especially useful in production since you should not commit secrets like your database password into your source control (such as Git).

$ cat config/database.yml
production:
  url: <%= ENV['DATABASE_URL'] %>

Now the behavior is clear, that we are only using the connection information in ENV['DATABASE_URL'].

Configuring an SQLite3 Database

Rails comes with built-in support for SQLite3, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using an SQLite database when creating a new project, but you can always change it later.

Here's the section of the default configuration file (config/database.yml) with connection information for the development environment:

development:
  adapter: sqlite3
  database: db/development.sqlite3
  pool: 5
  timeout: 5000

NOTE: Rails uses an SQLite3 database for data storage by default because it is a zero configuration database that just works. Rails also supports MySQL (including MariaDB) and PostgreSQL "out of the box", and has plugins for many database systems. If you are using a database in a production environment Rails most likely has an adapter for it.

Configuring a MySQL or MariaDB Database

If you choose to use MySQL or MariaDB instead of the shipped SQLite3 database, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: mysql2
  encoding: utf8mb4
  database: blog_development
  pool: 5
  username: root
  password:
  socket: /tmp/mysql.sock

If your development database has a root user with an empty password, this configuration should work for you. Otherwise, change the username and password in the development section as appropriate.

NOTE: If your MySQL version is 5.5 or 5.6 and want to use the utf8mb4 character set by default, please configure your MySQL server to support the longer key prefix by enabling innodb_large_prefix system variable.

Advisory Locks are enabled by default on MySQL and are used to make database migrations concurrent safe. You can disable advisory locks by setting advisory_locks to false:

production:
  adapter: mysql2
  advisory_locks: false

Configuring a PostgreSQL Database

If you choose to use PostgreSQL, your config/database.yml will be customized to use PostgreSQL databases:

development:
  adapter: postgresql
  encoding: unicode
  database: blog_development
  pool: 5

By default Active Record uses database features like prepared statements and advisory locks. You might need to disable those features if you're using an external connection pooler like PgBouncer:

production:
  adapter: postgresql
  prepared_statements: false
  advisory_locks: false

If enabled, Active Record will create up to 1000 prepared statements per database connection by default. To modify this behavior you can set statement_limit to a different value:

production:
  adapter: postgresql
  statement_limit: 200

The more prepared statements in use: the more memory your database will require. If your PostgreSQL database is hitting memory limits, try lowering statement_limit or disabling prepared statements.

Configuring an SQLite3 Database for JRuby Platform

If you choose to use SQLite3 and are using JRuby, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: jdbcsqlite3
  database: db/development.sqlite3

Configuring a MySQL or MariaDB Database for JRuby Platform

If you choose to use MySQL or MariaDB and are using JRuby, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: jdbcmysql
  database: blog_development
  username: root
  password:

Configuring a PostgreSQL Database for JRuby Platform

If you choose to use PostgreSQL and are using JRuby, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: jdbcpostgresql
  encoding: unicode
  database: blog_development
  username: blog
  password:

Change the username and password in the development section as appropriate.

Configuring Metadata Storage

By default Rails will store information about your Rails environment and schema in an internal table named ar_internal_metadata.

To turn this off per connection, set use_metadata_table in your database configuration. This is useful when working with a shared database and/or database user that cannot create tables.

development:
  adapter: postgresql
  use_metadata_table: false

Creating Rails Environments

By default Rails ships with three environments: "development", "test", and "production". While these are sufficient for most use cases, there are circumstances when you want more environments.

Imagine you have a server which mirrors the production environment but is only used for testing. Such a server is commonly called a "staging server". To define an environment called "staging" for this server, just create a file called config/environments/staging.rb. Please use the contents of any existing file in config/environments as a starting point and make the necessary changes from there.

That environment is no different than the default ones, start a server with bin/rails server -e staging, a console with bin/rails console -e staging, Rails.env.staging? works, etc.

Deploy to a Subdirectory (relative URL root)

By default Rails expects that your application is running at the root (e.g. /). This section explains how to run your application inside a directory.

Let's assume we want to deploy our application to "/app1". Rails needs to know this directory to generate the appropriate routes:

config.relative_url_root = "/app1"

alternatively you can set the RAILS_RELATIVE_URL_ROOT environment variable.

Rails will now prepend "/app1" when generating links.

Using Passenger

Passenger makes it easy to run your application in a subdirectory. You can find the relevant configuration in the Passenger manual.

Using a Reverse Proxy

Deploying your application using a reverse proxy has definite advantages over traditional deploys. They allow you to have more control over your server by layering the components required by your application.

Many modern web servers can be used as a proxy server to balance third-party elements such as caching servers or application servers.

One such application server you can use is Unicorn to run behind a reverse proxy.

In this case, you would need to configure the proxy server (NGINX, Apache, etc) to accept connections from your application server (Unicorn). By default Unicorn will listen for TCP connections on port 8080, but you can change the port or configure it to use sockets instead.

You can find more information in the Unicorn readme and understand the philosophy behind it.

Once you've configured the application server, you must proxy requests to it by configuring your web server appropriately. For example your NGINX config may include:

upstream application_server {
  server 0.0.0.0:8080;
}

server {
  listen 80;
  server_name localhost;

  root /root/path/to/your_app/public;

  try_files $uri/index.html $uri.html @app;

  location @app {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_redirect off;
    proxy_pass http://application_server;
  }

  # some other configuration
}

Be sure to read the NGINX documentation for the most up-to-date information.

Rails Environment Settings

Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails:

Using Initializer Files

After loading the framework and any gems in your application, Rails turns to loading initializers. An initializer is any Ruby file stored under config/initializers in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and gems are loaded, such as options to configure settings for these parts.

The files in config/initializers (and any subdirectories of config/initializers) are sorted and loaded one by one as part of the load_config_initializers initializer.

If an initializer has code that relies on code in another initializer, you can combine them into a single initializer instead. This makes the dependencies more explicit, and can help surface new concepts within your application. Rails also supports numbering of initializer file names, but this can lead to file name churn. Explicitly loading initializers with require is not recommended, since it will cause the initializer to get loaded twice.

NOTE: There is no guarantee that your initializers will run after all the gem initializers, so any initialization code that depends on a given gem having been initialized should go into a config.after_initialize block.

Initialization events

Rails has 5 initialization events which can be hooked into (listed in the order that they are run):

To define an event for these hooks, use the block syntax within a ::Rails::Application, ::Rails::Railtie or ::Rails::Engine subclass:

module YourApp
  class Application < Rails::Application
    config.before_initialize do
      # initialization code goes here
    end
  end
end

Alternatively, you can also do it through the config method on the Rails.application object:

Rails.application.config.before_initialize do
  # initialization code goes here
end

WARNING: Some parts of your application, notably routing, are not yet set up at the point where the after_initialize block is called.

Rails::Railtie#initializer

Rails has several initializers that run on startup that are all defined by using the initializer method from ::Rails::Railtie. Here's an example of the set_helpers_path initializer from Action Controller:

initializer "action_controller.set_helpers_path" do |app|
  ActionController::Helpers.helpers_path = app.helpers_paths
end

The initializer method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The :before key in the options hash can be specified to specify which initializer this new initializer must run before, and the :after key will specify which initializer to run this initializer after.

Initializers defined using the initializer method will be run in the order they are defined in, with the exception of ones that use the :before or :after methods.

WARNING: You may put your initializer before or after any other initializer in the chain, as long as it is logical. Say you have 4 initializers called "one" through "four" (defined in that order) and you define "four" to go before "four" but after "three", that just isn't logical and Rails will not be able to determine your initializer order.

The block argument of the initializer method is the instance of the application itself, and so we can access the configuration on it by using the config method as done in the example.

Because ::Rails::Application inherits from ::Rails::Railtie (indirectly), you can use the initializer method in config/application.rb to define initializers for the application.

Initializers

Below is a comprehensive list of all the initializers found in Rails in the order that they are defined (and therefore run in, unless otherwise stated).

Database pooling

Active Record database connections are managed by ::ActiveRecord::ConnectionAdapters::ConnectionPool which ensures that a connection pool synchronizes the amount of thread access to a limited number of database connections. This limit defaults to 5 and can be configured in database.yml.

development:
  adapter: sqlite3
  database: db/development.sqlite3
  pool: 5
  timeout: 5000

Since the connection pooling is handled inside of Active Record by default, all application servers (Thin, Puma, Unicorn, etc.) should behave the same. The database connection pool is initially empty. As demand for connections increases it will create them until it reaches the connection pool limit.

Any one request will check out a connection the first time it requires access to the database. At the end of the request it will check the connection back in. This means that the additional connection slot will be available again for the next request in the queue.

If you try to use more connections than are available, Active Record will block you and wait for a connection from the pool. If it cannot get a connection, a timeout error similar to that given below will be thrown.

ActiveRecord::ConnectionTimeoutError - could not obtain a database connection within 5.000 seconds (waited 5.000 seconds)

If you get the above error, you might want to increase the size of the connection pool by incrementing the pool option in database.yml

NOTE. If you are running in a multi-threaded environment, there could be a chance that several threads may be accessing multiple connections simultaneously. So depending on your current request load, you could very well have multiple threads contending for a limited number of connections.

Custom configuration

You can configure your own code through the Rails configuration object with custom configuration under either the config.x namespace, or config directly. The key difference between these two is that you should be using config.x if you are defining nested configuration (ex: config.x.nested.hi), and just config for single level configuration (ex: config.hello).

config.x.payment_processing.schedule = :daily
config.x.payment_processing.retries  = 3
config.super_debugger = true

These configuration points are then available through the configuration object:

Rails.configuration.x.payment_processing.schedule # => :daily
Rails.configuration.x.payment_processing.retries  # => 3
Rails.configuration.x.payment_processing.not_set  # => nil
Rails.configuration.super_debugger                # => true

You can also use Rails::Application#config_for to load whole configuration files:

# config/payment.yml:
production:
  environment: production
  merchant_id: production_merchant_id
  public_key:  production_public_key
  private_key: production_private_key

development:
  environment: sandbox
  merchant_id: development_merchant_id
  public_key:  development_public_key
  private_key: development_private_key

# config/application.rb
module MyApp
  class Application < Rails::Application
    config.payment = config_for(:payment)
  end
end
Rails.configuration.payment['merchant_id'] # => production_merchant_id or development_merchant_id

Rails::Application#config_for supports a shared configuration to group common configurations. The shared configuration will be merged into the environment configuration.

# config/example.yml
shared:
  foo:
    bar:
      baz: 1

development:
  foo:
    bar:
      qux: 2

# development environment
Rails.application.config_for(:example)[:foo][:bar] #=> { baz: 1, qux: 2 }

Search Engines Indexing

Sometimes, you may want to prevent some pages of your application to be visible on search sites like Google, Bing, Yahoo, or Duck Duck Go. The robots that index these sites will first analyze the http://your-site.com/robots.txt file to know which pages it is allowed to index.

Rails creates this file for you inside the /public folder. By default, it allows search engines to index all pages of your application. If you want to block indexing on all pages of your application, use this:

User-agent: *
Disallow: /

To block just specific pages, it's necessary to use a more complex syntax. Learn it on the official documentation.

Evented File System Monitor

If the listen gem is loaded Rails uses an evented file system monitor to detect changes when config.cache_classes is false:

group :development do
  gem 'listen', '~> 3.3'
end

Otherwise, in every request Rails walks the application tree to check if anything has changed.

On Linux and macOS no additional gems are needed, but some are required for *BSD and for Windows.

Note that some setups are unsupported.