A good place to start thinking about the Rails initialization process is with the files in railties/dispatches. Depending on your server software stack and dispatch method, incoming requests will hit one or another of the files in this folder. (If you want to know the details of the process for your particular server, take a look in railties/lib/commands/servers). I'll assume that the request is coming in through the pure ruby interface, instead of through one of the CGI interfaces. In that case, it will hit dispatch.rb:

So, at the very highest level, there are three things going on here:

You've probably looked at your application's config/environment.rb many times in the course of configuring your Rails applications. But now, it's time to look at it again in the context of initialization.

Stripped down to its essentials, and with no user-specified configuration, here's what you'll find in environment.rb:

The first step here is to specify the version of the Rails gem that you want to be using with this application. As you'll see in a bit, this is ignored if you're running vendored Rails. Then this file pulls in your boot.rb file. After that, Rails calls Initializer#run. Time to dig one level deeper.

In boot.rb - which Rails copies unchanged to your application's config folder from railties/environments - things start to happen. Here's an outline of the action:

This file first sets up the RAILS_ROOT constant to point to its own parent folder (which will be the root of your application). It then defines Rails and calls its boot! method. The rest of the details are located within the Rails module, still in the same file. The boot! method begins with a check to prevent re-entrancy, gives you a chance to do some very early initialization, and runs Rails:

The Rails.preinitialize method is the first chance that you have to run custom code. It loads the file config/preinitializer.rb in your application:

By default, this file does not exist; if you want to use it (perhaps to spin up some prerequisite of your application functionality) you'll have to define it yourself.

The pick_boot method decides whether to use vendored Rails or gem Rails, and then kicks it off:

Both VendorBoot and GemBoot inherit from Rails::Boot, which is where the run method called by boot! is actually defined:

In either case (vendored or gem Rails), the load_initializer bootstraps in some more code. If you're dealing with gem Rails, it loads the Rails gem (there's a bunch of code related to version checking both ruby gems and Rails involved, which I'm not going to wade through):

If you're going down the vendored Rails path, load_initializer is a bit different:

Rails::Initializer is defined in railties/lib/initializer.rb, and you'll see a great deal of it as this walkthrough progresses. Requiring this file drags in a great deal of other code:

So, before I dig into the first call to a method of Initializer, it's necessary to sidetrack for a look at the contents of these libraries. The logger, set, and pathname utilites are the parts of the Ruby Standard Library that Rails absolutely needs. The rest of these dependencies come out of Rails' own libraries. I'll proceed as if you're running vendored Rails, though of course the same libraries are also in gem Rails.

The railties_path library is simple: all it does is set up a single constant for use later in the process.

In your application, this will point to vendor/rails/railties.

This is another easy one. rails/version is where the version number of Rails is set:

Requiring rails/plugin/locator brings in the Rails::Plugin::Locator class and its subclasses. You'll see how these are used shortly - but just requiring this file doesn't run any code.

The rails/plugin/loader library starts with a requirement of its own:

This makes Rails::Plugin available. rails/plugin/loader itself sets up Rails::Plugin::Loader. At this point, Rails has all the machinery necessary to load plugins - but it hasn't loaded any of them yet.

Requiring rails/gem_dependency loads up Rails::GemDependency. Again, there's no initialization code in this file.

The rails/rack library uses autoload to lazy-load a couple more classes for use down the line:

It's time to take stock. The reason for looking at all of that code was that Rails was in the process of loading boot.rb. Specifically, the next step for vendored Rails is to call Rails::Initializer.run(:install_gem_spec_stubs):

This is part of the setup that vendored Rails does to allow plugin initialization to proceed smoothly. The idea is to allow plugins to depend on the various gems that make up Rails, even when the gem version of Rails isn't being loaded. So, after checking to make sure that none of the actual gems are already loaded, Rails manufactures fake gem specs that do nothing more than provide the name and version to fool any affected plugins into thinking that what they're looking for is already present.

OK, great - the Rails boot process is finished. What next? If you unwind your mental stack, you'll see that the next step is to process the Initializer.run method in +environment.rb:

Remember, at this point the various files required by Initializer have already been brought in as part of the boot process. So this code proceeds straight into the run method:

Rails first spins up a default configuration using Configuration.new and then uses the yield to allow any configuration arguments specified in your environment.rb to overwrite the default values. It then sets up a new Initializer instance to reference the altered configuration:

The Configuration class has a fairly fat initializer:

The first step here is to set the @root_path instance variable to the root of your Rails application:

After that, the initialize method calls various methods within the class to set up default class properties. I'll go into these later as they become pertinent to the rest of the initialization process. One that is immediately important, though, is default_frameworks. Unless you override this in your application's configuration file, this returns the full set of frameworks that make up Rails:

For each of the frameworks (as well as for active support, which you have no option to leave out), the Configuration object initializes an empty Rails::OrderedOptions object - an array that can hold configuration options.

TODO: Revisit that step in more detail

Now that there is a configured Initializer, whatever command was passed in to the run method gets executed by that initializer. By default, this is the process command, which steps through all of the available initialization routines in a pre-set order:

Whew! What a mouthful. Time to look at each of those initialization steps in order.

The check_ruby_version method makes sure that the application is trying to run on an acceptable version of ruby:

The check is implemented in an external file, railties/lib/ruby_version_check.rb, so that it's available to the rails application generator as well as the initialization code. At the moment, it accepts ruby 1.8.2 or anything from 1.8.4 to current.

You've already seen install_gem_spec_stubs above; it's called as part of the boot.rb processing.

The set_load_path method sets the global $LOAD_PATH variable based on two different configuration options. The method strips away any duplication between the two arrays:

The Configuration object delivers load_paths from its default_load_paths method:

Here, root_path is the application's base directory, which is set as part of the Configuration#initialize process. Rails puts together an array here that includes the locations of your controllers, any components subdirectories, and standard include paths. If you're running in the development environment, it also pulls in the internal Rails builtin folder:

The Configuration object delivers framework_paths from its framework_paths method:

This gets you the lib folders from all of the loaded frameworks as part of your loadpath.

Rails still isn't done finding places that it might have to load code from in the future. There still remains the possibility that you have some plugins loading as gems. The add_gem_load_paths method accounts for this possibility:

The call to add_frozen_gem_path makes sure that Rails will look in vendor/gems for gems before it goes hunting across the system. By default, the configuration does not load any gems, so this code will do nothing unless you specify some gems in your application's configuration file.

At this point, Rails knows where to find all of its own frameworks and gems (though note that it hasn't dug into plugin loading yet), so it's safe to require the ones that you've said you will actually use:

The next step is to set the paths from which Rails will automatically load files. These are further split up into load paths and "load once" paths:

You've already seen that Configuration#load_paths gives you all of the places in your application where code can reside (but not the framework paths). The +Configuration#load_once_paths method returns an empty array by default:

Yes, there are still more paths for Rails to deal with. Now it's time to bring in the paths for plugins:

The plugin loader is lazy-initialized from the active Configuration object:

Within the Configuration class, this in turn is just a reference to the Plugin::Loader class:

You'll see much more of the plugin loader as the initialization process continues; it has the primary responsibility for loading only the plugins you specify in your application's configuration, and bringing them in in the right order.

The plugin loader picks up the paths from each loaded plugin:

Inside the plugin loader, the plugins collection is initialized to an array of all plugins to be loaded, sorted by load order:

TODO: More detail on plugin loader

So far, all of the initialization has been the same whether you're running in product, development, or test. The load_environment method is where Rails finally picks up the configuration file for the current environment from your application's config/environment folder and processes it:

TODO: Perhaps some more detail on what's going on here.

Rails determines which environment to process by looking at environment_path:

And that in turn gets its information from the environment method:

And RAILS_ENV itself is set up to read from the environment of the Rails process, with a default to development:

The initialize_encoding method is one of the few places in Rails where you'll find an explicit dependency on the version of ruby that's running:

For ruby 1.8, this sets a constant that will enable multibyte-safe operations elsewhere in Rails. For ruby 1.9, Rails doesn't have to worry about doing anything special.

The initialize_database method will actually get in touch with your application's configured database for the first time:

There's no point in doing this if your application isn't using Active Record, of course. If it is, this method configures ActiveRecord::Base from the current database configuration file. This defaults to config/database.yml, though that's a property of the Configuration object so you could override it if you wanted to:

The Configuration#database_configuration method processes this file through ERB first, and then through YAML:

ActiveRecord::Base.configurations is defined in /activerecord/lib/activerecord/base as a simple class accessor which stores the processed hash of options out of database.yml. This is used by establish_connection to set up the initial connection pool with the database.

The initialize_cache method brings up Active Support's cache and sets up the RAILS_CACHE constant, unless this has already been done:

Despite its name, initialize_framework_caches currently only initializes one cache, by passing RAILS_CACHE over to Action Controller:

The initialize_logger method brings Rails' logging online:

By default, this method uses ActiveSupport::BufferedLogger, which stores up data in memory for an adjustable length of time before flushing it out to the hard drive. You can override this by explicitly defining a logger class in your configuration file. Note that if Rails is unable to create the actual log for any reason, it cranks up the logging level to WARN and starts dumping log output to the console to get your attention.

Now that Rails has its own default logger, it passes this logger down to the various frameworks. This method is designed to be non-destructive: that is, if a framework already has its own logger initialized, then the master logger will not overwrite that.

As you know, Rails caches things differently depending on whether it is in production or development mode: in development mode, your classes get reloaded on each request. The initialize_dependency_mechanism method looks at the value you've specified for cache_classes and tells ActiveSupport::Dependencies about it:

TODO: Might be worth digging a bit deeper here

"Whiny nils" is the Rails term for putting warnings into the log whenever a method is invoked on a nil value, with (hopefully) helpful information about which sort of object you might have been trying to use. This is handled by bringing in a special chunk of code if it's called for:

Next up is getting ready to store session information:

If Rails can't find your configured session path for some reason, it uses Dir::tmpdir to store sessions rather than raising an error.

The initialize_time_zone method sets the default timezone for the Time class. It also sets up ActiveRecord to be timezone-aware.

If there is no valid timezone information in the configuration, this method will raise an error. However, the Configuration class does not include a default timezone. This is why Rails automatically generates a config.timezone setting in environment.rb:

At this point, the prerequisites are in place to start bringing the actual Rails frameworks to life. The initialize_framework_settings method is responsible for configuring each of the loaded frameworks:

The Configuration class includes accessors corresponding to each of the frameworks:

So, when the initialize_framework_settings method runs, it takes, for example, all of the options from Configuration#active_record and passes them to ActiveRecord#Base. This is what makes it possible to handle settings like config.active_record.schema_format = :sql in your environment.rb or other configuration files.

TODO: It would be really nice to have a good list of framework configuration options

The initialize_framework_views method sets the path to the application's views for the two frameworks that might need it:

By default, the view_path is set up to point to your app/views folder, but you could override this in your configuration file:

Initializing a Path object from this creates a frozen copy. Here's Path#initialize:

Setting up the view paths actually causes some processing. Here's what happens in ActionController::Base:

If you look into process_view_paths, you'll see that it creates a new instance of ActionView::PathSet:

So, by default, Rails creates a new PathSet object and passes it an array containing a single Path object that points to your application's app/views folder.

TODO: Figure out the PathSet code

Here's the default definition of the add_support_load_paths method:

This appears to be a do-nothing method.

TODO: What's up with this? I don't see that it's ever overridden either.

The load_gems method calls load on each ruby gem known to the configuration:

The load_plugins method loads your application's plugins by calling the load_plugins method of the plugin loader, which was itself initialized earlier in the add_plugin_load_paths method:

Within the Plugin::Loader class, the load_plugins method iterates across all of the plugins for your application:

The Plugin::load method is the one that actually evaluates the init.rb file within each plugin. After this, the plugin instance is added to the Initializer#loaded_plugins collection. When that's finished, there's an explicit sanity check to make sure that at least all of the plugins listed in your configuration files are loaded:

TODO: More details on the Plugin class. Though actually that might be another guide.

Rails isn't quite done dealing with gems yet. The next step is to add the paths to any frozen gems, via add_gem_load_paths:

Now Rails calls load_gems for the second time. Why twice? The first time loads up any gems that can be easily found that might be needed by plugins. Then plugins are initialized, and then Rails builds up additional path information for gems. After this, it can make a final pass to load up the rest of the configured gems.

After two tries at loading gems, there's a sanity check to make sure that everything you claimed to depend on is actually present:

TODO: Need a fair amount more detail on gem loading, preferably after that code settles down.

With gems and plugins available, Rails can finally start running some of the code in your own application. First up are any files you've dropped in the config/initializers folder:

You can supply your own after_initialize block by setting config.after_initialize in your configuration files. Indeed, you can even supply an array of such blocks if you like. This is the point in the process where Rails will run your after_initialize code.

Some pieces, notably observers and routing, have not yet been set up by Rails at the point where this block is called.

The Rails dispatcher is the piece that handles sending incoming HTTP requests to their proper controller for processing. Setting it up takes a few lines of code:

There's no point in setting up the dispatcher if you're not loading Action Controller. If you are, then a require statement brings in the code in railties/lib/dispatcher.rb. This is just a wrapper that brings up the application's instance of ActionController::Dispatcher:

The dispatcher deserves a guide of its own (and perhaps I'll write on eventually), but for now, I just want to mention its participation in the initialization process. The define_dispatcher_callbacks method is the one that sets up the "reload classes on every request" behavior that Rails exhibits in development mode:

TODO: to_prepare comes into this somehow (setting up for the :prepare_dispatch) but I don't immediately see how.

The Dispatcher needs the information from your routes.rb file to do its work, but this information needs to be processed from the DSL you write in that file to an internal data structure first. That's the job of initialize_routing:

Again, there's no point in running this code if you don't have Action Controller loaded in your application.

Rails next instantiates any observer classes you've declared:

TODO: Maybe worth looking at observer details

Next, Rails figures out how to find its views:

The eager_load_templates flag tells the ActionView::Path class to freeze each template as it is loaded; this is turned on in the same circumstances as Rails' model cache (i.e., in production by default). After setting this flag, Rails loads templates for controllers and for mailers (assuming that those frameworks are in use). The applicable paths were set earlier in the initialization process by the initialize_framework_views method.

Loading templates amounts to freezing cached copies in memory after eager loading any methods:

TODO: Probably need more detail

The load_application_classes method is the point where Rails brings in all the classes that it keeps loaded for the duration of your application, if you're in production mode:

The default configuration puts models, helpers, and controllers into the eager load paths:

So, Rails ends up calling require_dependency on each ruby file found in these folders (and their sub-folders). This method is defined in activesupport/lib/active_support/dependencies.rb:

The depend_on method calls require_or_load:

The require_or_load method goes through a fair bit of gyration, but the end result (in production) is to use require to pull in the specified file.

The final step of Initializer#process is to turn off automatic dependency loading:

At this point, Rails has worked its way through environment.rb and boot.rb and completed it laundry list of initialization actions. There are only a few remaining steps on the way to being ready to dispatch requests. If you recall, I started off this discussion by looking at dispatch.rb, where the next line of code is:

This brings in railties/lib/dispatcher.rb, which does nothing more than call up the dispatcher from Action Controller and create a constant for this class that will be used throughout your application:

Next up in dispatch.rb is:

This is fossil code. It only executes if Apache::RubyRun is defined, and that is defined by mod_ruby. You're not running mod_ruby, so don't worry about it.

At last, time to actually dispatch a request. Here's the starting point for the code, as defined in dispatch.rb:

The dispatch method takes three arguments, all of which have defaults:

As you can see, this falls through to dispatch_cgi, which builds up new request and response objects:

TODO: Figure out how this rabbit gets into this hat

With the request and response objects, it's off to the unadorned dispatch method:

This dispatch method needs to worry some about thread safety. If you're running in threaded mode - as you will be if you specify config.threadsafe! in one of your environment files - then it falls straight through to dispatch_unlocked. If you're not in threaded mode, it may have to wait for another request to be processed before it gets to dispatch_unlocked:

Here's the heart of handling a request: run the :before_dispatch callbacks, handle the request, then run the :after_dispatch callbacks.

You saw dispatcher callbacks above in the discussion of the Initializer#prepare_dispatch method. By default, Rails sets up two callbacks in development mode, and none in production or test modes:

The Dispatcher#reload_application callback takes care of making sure that the latest changes to the application are loaded:

You've already seen all of those initializations discussed; all the reload_application method does is re-run selected parts of the initialization process.

Handling the request is a two-step process:

The first step is to call the route recognizer to figure out which controller should deal with the request at hand.

The second step is to hand the actual request and response objects to that controller, and tell it to do its thing. Digging into that is a subject for another guide.

In production mode (or any time you've set config.cache_classes = false), Rails finishes the dispatch process for a single request by calling the Dispatcher#cleanup_application method:

The point here is to clear the loaded classes back out of memory, so they can be reloaded on the next request without any conflicts.

TODO: One more level of detail on this?

If you've followed along this far, congratulations! You now understand the basics of what Rails has to do before it can handle a simple request for +http://localhost:3000/blogs/1. More importantly, you should have a good idea of the various knobs that you can turn to customize the process, and their effects on the overall behavior of Rails.

TODO: Further doc of config.threadsafe!. Anything else that can be set in configs that isn't used in the main line?