9780596521424
production_id35801033.html

Chapter 11. Production Environments

When you're ready to share your application with the world, you need to get it running on a Web server connect to the Internet. This process has three basic steps:

  1. Configure your Production environment.

  2. Set up your Web server.

  3. Deploy your application to the new server.

No two production environments are ever quite the same. Each application has its own unique set of dependencies, and depending on your operating system of choice, configuration step can vary wildly. For the sake of simplicity, this chapter assumes you'll deploy to a vanilla Linux server running the wildly popular Apache web server.

Before we can talk about servers and deployment, we need to know what it means to run your application in production mode, or in Rails-lingo, under the production environment.

Rails Environments

Every Rails application is pre-configured with three standard environments: development, testing, and production. Each environment has its own database connection defined in database.yml and loads a unique configuration file for the task at hand.

The default environment is development. The following settings are defined in config/environments/development.rb:

Example::Application.configure do
  # Settings specified here will take precedence over those in config/environment.rb

  # In the development environment your application's code is reloaded on
  # every request.  This slows down response time but is perfect for development
  # since you don't have to restart the webserver when you make code changes.
  config.cache_classes = false

  # Log error messages when you accidentally call methods on nil.
  config.whiny_nils = true

  # Show full error reports and disable caching
  config.consider_all_requests_local       = true
  config.action_view.debug_rjs             = true
  config.action_controller.perform_caching = false

  # Don't care if the mailer can't send
  config.action_mailer.raise_delivery_errors = false
end

This environment is optimized up for running locally on a developer's computer. Full error messages are displayed, caching is disabled, and classes are automatically reloaded, so you don't have to stop & start your application to pick up code changes.

The test environment is used when running Rails built in test suite. The tests run in their own database, and Action Mailer is configured avoid actually sending and email messages.

The production environment is configured for speed and security. Caching is enabled, classes are not reloaded, and error messages only have simple error codes, instead of full back traces and session information. This is complete configuration defined in config/environments/production.rb.

Example::Application.configure do
  # Settings specified here will take precedence over those in config/environment.rb

  # The production environment is meant for finished, "live" apps.
  # Code is not reloaded between requests
  config.cache_classes = true

  # Full error reports are disabled and caching is turned on
  config.consider_all_requests_local       = false
  config.action_controller.perform_caching = true

  # See everything in the log (default is :info)
  # config.log_level = :debug

  # Use a different logger for distributed setups
  # config.logger = SyslogLogger.new

  # Use a different cache store in production
  # config.cache_store = :mem_cache_store

  # Disable Rails's static asset server
  # In production, Apache or nginx will already do this
  config.serve_static_assets = false

  # Enable serving of images, stylesheets, and javascripts from an asset server
  # config.action_controller.asset_host = "http://assets.example.com"

  # Disable delivery errors, bad email addresses will be ignored
  # config.action_mailer.raise_delivery_errors = false

  # Enable threaded mode
  # config.threadsafe!
end

Changing Environments

You can specify the environment to use when starting your Rails server.

rails server -e [name], --environment=[name]

Console, etc.

You can also set a RAILS_ENV environment variable in your shell, and Rails will use it as a default.

In BASH, on most Linuxes and Mac OS X:

set RAILS_ENV = production

or on Windows:

...

Server setup

While it is entirely possible to run rails server --environment=production --port=80, and have a production web server up and running in mere seconds, you would quickly notice that the performance leaves a lot to be desired.

The rails server command launches a very simple ruby web server to host your application. This has a serious limitation. Rails runs as a single-threaded application, and can only respond to one HTTP request at a time. When multiple users try to access the site simultaneously, their requests queue up and are executed one at a time. It doesn't take long for the queue to back up, and everything to slow to a crawl.

As Rails has matured, the best ways to fix this problem have evolved and changed, but they all work on the same basic principal: Launch multiple Rails processes, and have a single Internet-facing web server hand requests down to the individual processes to be processed concurrently. This scales very well. As traffic increases, you can simply spawn more Rails processes to handle more simultaneous requests.

Phusion has released a fantastic tool called Passenger (also sometimes referred to as mod_rails) that abstracts and simplifies this process. It can be configured with the popular Apache web server, or the lightning fast Nginx. Passenger will automatically spawn Rails processes for you as needed, and as long as system resources are available.

Note

This chapter will assume you're using the Apache web server. If you wish to use the faster, but more esoteric Nginx server, consult the documentation at http://modrails.com.

Installing Passenger for Apache

Passenger is first installed as a gem:

$ gem install passenger
Building native extensions.  This could take a while...
Successfully installed passenger-2.2.11
1 gem installed
Installing ri documentation for passenger-2.2.11...
Installing RDoc documentation for passenger-2.2.11...

Next, we need to build the Apache module:

$ passenger-install-apache2-module
Welcome to the Phusion Passenger Apache 2 module installer, v2.2.11.

This installer will guide you through the entire installation process. It
shouldn't take more than 3 minutes in total.

Here's what you can expect from the installation process:

 1. The Apache 2 module will be installed for you.
 2. You'll learn how to configure Apache.
 3. You'll learn how to deploy a Ruby on Rails application.

Don't worry if anything goes wrong. This installer will advise you on how to
solve any problems.

Press Enter to continue, or Ctrl-C to abort.

Press Enter and Passenger will check for dependencies and compile the module.

ENTER
Checking for required software...

 * GNU C++ compiler... found at /usr/bin/g++
 * Ruby development headers... found
 * OpenSSL support for Ruby... found
 * RubyGems... found
 * Rake... found at /usr/bin/rake
 * rack... found
 * Apache 2... found at /usr/sbin/httpd
 * Apache 2 development headers... found at /usr/sbin/apxs
 * Apache Portable Runtime (APR) development headers... found at /usr/bin/apr-1-config
 * Apache Portable Runtime Utility (APU) development headers... found at /usr/bin/apu-1-config

Once Passenger finished compiling the Apache module, it will tell you how to load the module into Apache.

The Apache 2 module was successfully installed.

Please edit your Apache configuration file, and add these lines:

   LoadModule passenger_module /var/lib/gems/1.8/gems/passenger-2.2.11/ext/apache2/mod_passenger.so
   PassengerRoot /var/lib/gems/1.8/gems/passenger-2.2.11
   PassengerRuby /usr/bin/ruby1.8

After you restart Apache, you are ready to deploy any number of Ruby on Rails
applications on Apache, without any further Ruby on Rails-specific
configuration!

Press ENTER to continue.

The three lines of code allow Apache to load the Passenger module, and tell Passenger where it to find its gem and the Ruby interpreter. Copy the values Passenger displays (they may be different than what is printed here) and add them to the end of your Apache config. On most Linux distributions, this will be a file named apache2.conf or httpd.conf located in /etc/apache2/ or /etc/httpd. Consult your distribution's documentation if you're having trouble finding it.

Press the Enter key, and Passenger will display the next set of instructions.

Deploying a Ruby on Rails application: an example

Suppose you have a Rails application in /somewhere. Add a virtual host to your
Apache configuration file and set its DocumentRoot to /somewhere/public:

   <VirtualHost *:80>
      ServerName www.yourhost.com
      DocumentRoot /somewhere/public    # <-- be sure to point to 'public'!
      <Directory /somewhere/public>
         AllowOverride all              # <-- relax Apache security settings
         Options -MultiViews            # <-- MultiViews must be turned off
      </Directory>
   </VirtualHost>

And that's it! You may also want to check the Users Guide for security and
optimization tips, troubleshooting and other useful information:

  /Users/oreilly/.gem/ruby/1.8/gems/passenger-2.2.11/doc/Users guide Apache.html

Enjoy Phusion Passenger, a product of Phusion (www.phusion.nl) :-)
http://www.modrails.com/

Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.

This next step tells Passenger where find your application's code, and links it to the domain name you wish to use. Now would be a great time to upload your application's source code to your server, if you haven't done so already.

We'll be adding a virtual host reference for your site. You'll have to change the ServerName to your application's domain, and update the DocumentRoot and Directory declarations with the path to your app's public directory on the server (not the application root!).

This can be added to same Apache config file we just used, but most Linux distributions provide a way to organize virtual hosts into individual files. You may find examples in vhosts.d or sites-enabled in the /etc/apache2 or /etc/httpd directories. Consult your distribution's documentation on Apache virtual hosts for best practices.

You can repeat the virtual host configuration to set up as many virtual hosts running as many different Rails applications as you'd like. The module loading only has to be done once.

Finally, restart Apache to load the new Passenger module, and configuration changes.

$ /etc/init.d/apache2 restart
 * Starting apache2 ...                     [ ok ]

That's it! Your Rails application is up and running.

Managing deployments

With server setup out of the way, we've left with a messy task: continual deployment. As you continue to develop and improve your application, you'll periodically update the code running on your web server. If done by hand, this can be a tedious and error prone process, especially if you have several developers working together, or if your application is running across several web servers.

Capistrano is a tool that removes much of this pain and error.

If you use a source control system like Git or Subversion, Capistrano can deploy your application directly from source control, eliminating any discrepancies that tend to sneak in with manually copied files. Capistrano will also run your database migrations, so your production database schema is never out of sync with the codebase.

Common Capistrano tasks

Capistrano has a Rake-like interface. You run it from the command line anywhere in your application tree, and it loads in the setup via the first Capfile it finds. Here are the most common tasks:

cap deploy - Push the latest code changes out all web servers.

cap deploy:setup - Set up a web server for use with Capistrano. Non-destructive when run on a pre-configured server.

cap deploy:migrations - Push the latest code changes out to all web servers and migrate the database to the latest version.

cap deploy:rollback - Roll back all web servers to the last deployed version.

cap deploy:cleanup - Remove all but the most recent 5 deployed versions.

Installing Capistrano

First, install Capistrano via RubyGem:

$ gem install capistrano
Successfully installed capistrano-2.5.18
1 gem installed
Installing ri documentation for capistrano-2.5.18...
Installing RDoc documentation for capistrano-2.5.18...

Next, generate the basic configuration files by running the capify command with the path to your application.

$ capify /path/to/application
[add] writing '/path/to/application/Capfile'
[add] writing '/path/to/application/config/deploy.rb'
[done] capified!

This generates two files for us: Capfile and deploy.rb. The Capfile is mostly harmless, and can be ignored. It ensures the proper version of Capistrano is available on the system, loads the default tasks, and loads your custom configuration from deploy.rb.

The deploy.rb file is much more interesting, as it holds your unique configuration settings.

Configuring Capistrano

[default cap config here]

Server directory structure

[needs markup]

releases - Contains timestamped copies of your application code for each deployment.

current - Symlinked to the currently running deployment.

shared - Shared files across deployments. Database.yml, log files, etc.

Custom Environments

[this section is still in process]

There are times when the three basic Rails' environments don't quite cut it. What if you need to host a staging server?

Step 1: create staging.rb

Step 2: make necessary changes

Step 3: set passenger rails_env

Step 4: bringing it all together with multistage capistrano

Note: Don't hardcode ENV checks in your code or I will cut you.

Deployment with JRuby

JRuby is an implementation of Ruby that runs directly on the Java Virtual Machine. It offers some impressive performance improvements as well as an intriguing way to backdoor Ruby into the most conservative enterprise environments.

JRuby Advantages

Integration with Java Libraries

When run with JRuby, Ruby code can access Java Libraries, and visa-versa.

Improved performance

Though it can be hard for a diehard Rubyist to admit, the JVM is very highly tuned for performance. Much moreso than the standard Ruby 1.8.7 interpreter. The JVM offers improved garbage collection and native threading. Ruby's garbage collector is a notorious bottleneck, and the green threads implementation cannot take advantage of multiple cores or CPUs. The JVM has none of these disadvantages.

Deploy to a Java EE Application Server

JRuby lets you easily deploy to popular application servers like Tomcat, GlassFish, and Jetty. This can be a political advantage as well as a technical one. When you can deliver a compiled .war file for your Rails application, curmudgeonly sysadmins can easily deploy your new app to existing Java app servers with no special software or server configuration.

High performance Ruby on Windows

JRuby is currently the best way to run a high performance Rails application on the Windows, thanks to the JVM's cross-platform capabilities. While it is possible to use the Windows Ruby port, it can't compare to JRuby's performance or the simplicity of integrating with a Java app server.

JRuby may soon face some competition in this area. IronRuby implements the Ruby language on the CLR, bringing Ruby to Microsoft's .Net platform. While not yet Rails 3-compatible, it may eventually displace JRuby as the best Windows deployment environment. It is already a viable platform for Rails 2.x applications, and has shown some impressive benchmarks.

JRuby Disadvantages

No native C extensions

Any gems that rely on native extensions written in C cannot be loaded by JRuby. Thankfully, there are Java-friendly alternatives to almost all of these, but a little extra research when working with external libraries.

A smaller community means less support

JRuby is a minority within the Rails community. This means that there are fewer people to help when something unexpected goes wrong. The funding was cut for the much-loved GlassFish gem when Oracle bought out Sun and inheritted the project. Time will tell if the volunteer community can maintain this great deployment tool without commercial support.

Getting started with JRuby on Rails

Install JRuby

First, you must install JRuby. It is available for download from http://jruby.org. JRuby provides its own implementation of all the Ruby command line tools like ruby, irb, and gem. It also provides aliases prefixed with the letter J, so that you can easily have Ruby and JRuby installed and the same computer and easily switch between them.

We'll use the j-prefixed versions, jruby, jirb, and jgem, in our examples to avoid any possible confusion, though it is not strictly necessary that you use this syntax.

Install Rails and JDBC adapters

Now that JRuby is installed, let's install the Rails gem.

$ jgem install rails --pre
Successfully installed activesupport-3.0.0.beta4
Successfully installed builder-2.1.2
Successfully installed i18n-0.4.1
Successfully installed activemodel-3.0.0.beta4
Successfully installed rack-1.1.0
Successfully installed rack-test-0.5.4
Successfully installed rack-mount-0.6.4
Successfully installed tzinfo-0.3.22
Successfully installed abstract-1.0.0
Successfully installed erubis-2.6.5
Successfully installed actionpack-3.0.0.beta4
Successfully installed arel-0.4.0
Successfully installed activerecord-3.0.0.beta4
Successfully installed activeresource-3.0.0.beta4
Successfully installed mime-types-1.16
Successfully installed polyglot-0.3.1
Successfully installed treetop-1.4.8
Successfully installed mail-2.2.4
Successfully installed actionmailer-3.0.0.beta4
Successfully installed thor-0.13.6
Successfully installed railties-3.0.0.beta4
Successfully installed bundler-0.9.26
Successfully installed rails-3.0.0.beta4
23 gems installed

Next, we need to install the Active Record adapters for Java Database Connectivity. Let's install the JDBC library for SQLite, since that is Rails' default database type.

$ jgem install activerecord-jdbcsqlite3-adapter
Successfully installed activerecord-jdbc-adapter-0.9.7-java
Successfully installed jdbc-sqlite3-3.6.3.054
Successfully installed activerecord-jdbcsqlite3-adapter-0.9.7-java
3 gems installed

If you plan on connecting to Microsoft SQL Server, MySQL, or PostgreSQL, you will need to install the activerecord-jdbcmssql-adapter, activerecord-jdbcmysql-adapter, or activerecord-jdbcpostgresql-adapter gems, respectively.

Creating a JRuby on Rails application

Creating a JRuby on Rails application almost extra like creating a standard Rails app. The only difference is that we need to tell Rails to load the JDBC drivers so that it can talk to our database. Thankfully, JRuby provides a template that sets all that up for us. We just need to specify it when we generate the app.

$ jruby -S rails new my_jruby_app --template=http://jruby.org/rails3.rb
      create  
      create  README
      create  Rakefile
      # truncated ...
      create  vendor/plugins
      create  vendor/plugins/.gitkeep
       apply  http://jruby.org/rails3.rb
       apply    http://jruby.org/templates/default.rb
        gsub      Gemfile

By prefixing the rails command with jruby -S, we ensure that we're loading the JRuby interpreter, and not the default Ruby interpreter on your system. If JRuby is the only Ruby on your box, or it has the highest precedence in your PATH, you can skip the extraneous jruby -S.

The template automatically adds this snippet to the Gemfile for requiring the JDBC gems.

if defined?(JRUBY_VERSION)
  gem 'activerecord-jdbc-adapter'
  gem 'jdbc-sqlite3', :require => false
else
  gem 'sqlite3-ruby', :require => 'sqlite3'
end

That's it for a basic JRuby installation. The normal rails server command will fire up the server with WEBrick so you can confirm everything is hooked up correctly.

$ jruby -S rails server
=> Booting WEBrick
=> Rails 3.0.0.beta4 application starting in development on http://0.0.0.0:3000
=> Call with -d to detach
=> Ctrl-C to shutdown server
[2010-06-14 05:04:48] INFO  WEBrick 1.3.1
[2010-06-14 05:04:48] INFO  ruby 1.8.7 (2010-06-06) [java]
[2010-06-14 05:04:48] INFO  WEBrick::HTTPServer#start: pid=60063 port=3000

Running Rails on GlassFish

That was an awful lot of work just to launch crusty, old WEBrick. Let's get our JRuby app up and running with GlassFish—a high performance Java EE Application Server. Thankfully there's a great glassfish gem that takes care of the hard work for us.

It can be installed like any other gem.

$ jgem install glassfish
Successfully installed glassfish-1.0.2-universal-java
1 gem installed

You can fire up a GlassFish server by running the glassfish command in the root of your application.

$ glassfish
Starting GlassFish server at: 0.0.0.0:3000 in development environment...
Writing log messages to: /Users/nutshell/jruby_on_rails/log/development.log.
Press Ctrl+C to stop.

You can access your server at http://localhost:3000, just like with WEBrick in our last example.

GlassFish options

The glassfish command takes several options, many of which will look similar to those used with rails server.

glassfish [options...] [path_to_application]

The following options are available:

-p PORT, --port=PORT

Specify the server port. The default is 3000.

-a HOST, --address=HOST

Bind to the host address. The default is 0.0.0.0.

-e ENV, --environment=ENV

Specify the Rails environment. The default is development.

-n NUM, --runtimes=NUM

Number of JRuby runtimes to spawn at launch.

--runtimes-min NUM

Minimum number of JRuby runtimes to maintain.

--runtimes-max NUM

Maximum number of JRuby runtimes to create.

-P FILE, --pid FILE

When running as a daemon, store the PID in the specified file.

-l FILE, --log=FILE

Log server messages to the specified file. The default is log/development.log.

--log-level=LEVEL

Specify the log level. Valid values are between 0 and 7. The default is 3 (info).

--config=FILE

Path to configuration file. The default is config/glassfish.yml.

The glassfish gem also comes with a support rake-based tool: gfrake. It supports the following commands:

gfrake command

clean

Remove temporary files from tmp/.glassfish.

config

Generates a sample config file in config/glassfish.yml.

Configuring GlassFish

The gfrake config command will generate a sample YAML configuration file. It provides very detailed configuration options for the GlassFish server. The file is well documented, which makes it quite easy to manage.

#
# GlassFish configuration.
#
# Please read the comments for each configuration settings before modifying.
#

# application environment. Default value development
environment: development


# HTTP configuration
http:

    # port
    port: 3000
    
    #address
    address: 0.0.0.0

    # context root. The default value is '/'
    contextroot: /

    # Grizzly is NIO based HTTP libraries used by GlassFish gem
    grizzly:
        #HTTP chunking enable/disable
        chunking-enabled: true

        # Time after which the request times out in seconds
        request-timeout: 30
        
        #Send buffer size
        send-buffer-size: 8192
        
        #maximum number of keep-alive connections
        max-keepalive-connextions: 256
        
        #Keep Alive timeout, max time a connection can be deemed as idle and kept
        #in the keep-alive state
        keepalive-timeout: 30
                        
        #http thread pool used by Grizzly
        thread-pool:
            #Idle threads are removed from pool, after this time (in seconds)
            idle-thread-timeout-seconds: 900

            #The maxim number of tasks, which could be queued on the thread pool.
            #-1 disables any maximum checks.
            max-queue-size: 4096

            #Maximum number of threads in the threadpool servicing
            #requests in this queue. This is the upper bound on the no. of
            #threads that exist in the threadpool.
            max-thread-pool-size: 5

            #Minimum number of threads in the threadpool servicing
            #requests in this queue. These are created up front when this
            #threadpool is instantiated
            min-thread-pool-size: 2                

#Logging configuration
log:

    # Log file location. Default log file is log/<environment>.log. For 
    # example, if you are running in development environment, then the log 
    # file would be log/development.log.
    #
    # The log-file value must be either an absolute path or relative to your 
    # application directory.
    
    #log-file:

    # Logging level. Log level 0 to 7. 0:OFF, 1:SEVERE, 2:WARNING,
    # 3:INFO (default), 4:FINE, 5:FINER, 6:FINEST, 7:ALL.
    log-level: 3

#
# Runtime configuration
# If you are using Rails ver < 2.1.x, you should configure the JRuby runtime 
# pool for increased scalability.
jruby-runtime-pool:

    # Initial number of jruby runtimes that Glassfish starts with. It defaults
    # to one. It also represents the lowest value that Glassfish will use for
    # the maximum and the highest value that Glassfish will accept for the
    # minimum. As of this time, setting this number too high may cause
    # undesirable behavior. Default value is .
    initial: 1

    # Minimum number of jruby runtimes that will be available in the pool.
    # It defaults to one. The pool will always be at least this large, but
    # may well be larger than this. Default value is 1.
    min: 1


    # Maximum number of jruby runtimes that may be available in the pool.
    # It defaults to two. The pool will not neccessarily be this large.
    # Values that are too high may result in OutOfMemory errors, either in
    # the heap or in the PermGen. Default value is 1.
    max: 1

daemon:
    # Run GlassFish as a daemon. GlassFish may not run as a daemon process
    # on all platforms. Default value is false.
    enable: false

    # File where the process id of GlassFish is saved when run as daemon.
    # The location must be either an absolute path or relative to your 
    # application directory.
    # default PID file is tmp/pids/glassfish-<PID>.pid
    
    #pid:

    # Like JRuby GlassFish gem runs on Java Virtual Machine. You can pass
    # JVM properties using 'jvm-options' property. The JVM options must be
    # SPACE seprated.
    # 'jvm-options. property can ONLY be used only in daemon 
    # mode. The numbers below are to give an ideas. The numbers in your case 
    # would vary based on the hardware capabilities of machine you are 
    # running. See what is a server class machine 
    # http://java.sun.com/javase/6/docs/technotes/guides/vm/server-class.html

    # GlassFish gem runs with these default options
    #
    #jvm-options: -server -Xmx512m -XX:MaxPermSize=192m -XX:NewRatio=2 -XX:+DisableExplicitGC -Dhk2.file.directory.changeIntervalTimer=6000

    # Values below are given for a Sun Fire x4100, 4x Dual Core Opteron, 8G 
    # mem machine. You may like to changes these values according to the 
    # hardware you plan to run your application on. For details see
    # JVM ergonomics document, 
    # http://java.sun.com/javase/6/docs/technotes/guides/vm/gc-ergonomics.html
    #
    #jvm-options: -server -Xmx2500m -Xms64m -XX:PermSize=256m -XX:MaxPermSize=256m -XX:NewRatio=2 -XX:+DisableExplicitGC -Dhk2.file.directory.changeIntervalTimer=6000

Running Multithreaded Rails

The true power of a Java app server like GlassFish becomes apparent when we run Rails with multiple threads. This mode enables GlassFish to thread a single Rails process over all the CPUs and cores a server has to offer. A traditional process-based model used by servers like Passenger, Unicorn, and Mongrel has to spawn at least one process per-core, per-cpu to effectively utilize a server's resources. With today's multi-core, multi-cpu servers, this consumes a very large amount of memory. The threaded model is simplely more efficient, but is only practice because the JVM provides high-performance native threads compared to Ruby's highly limited green threads.

To enable multithreading in production, open the production.rb environment and uncomment the following line.

# Enable threaded mode
config.threadsafe!

Warning

Running an application with multiple threads introduces a brand new vector for hard-to-reproduce bugs. In addition to making sure your own code is threadsafe, you also need to confirm any plugins and gems you are using are safe. The web site railsplugins.org provides an excellent listing of Rails plugins, including information on threadsafety and compatibility with JRuby and Rails 3.

Create a Web Application Archive

The warbler gem allows you to compile your application into a .war file for easy deployment to Java Application Servers like Tomcat and Jetty.

It is installed just like any other gem.

$ jgem install warbler
Successfully installed warbler-1.1.0
1 gem installed

The warble command will build a basic .war file for your application.

$ warble
rm -f jruby_on_rails.war
Creating jruby_on_rails.war

It supports a few simple options.

executable

Embeds an excutable web server in the archive. The server can be launched by a directly by the Java interpreter:

$ java -jar jruby_on_rails.war
[Winstone 2010/06/14 06:41:16] - Beginning extraction from war file
[Winstone 2010/06/14 06:41:26] - Winstone Servlet Engine v0.9.10 running: controlPort=disabled
[Winstone 2010/06/14 06:41:26] - HTTP Listener started: port=8080
[Winstone 2010/06/14 06:41:45] - Winstone shutdown successfully
gemjar

Packages all gems specified in the Gemfile in the .war file.

war

Builds a .war file. When using the executable or gemjar options, you must explicitly add the war option in order to trigger the build. For example:

$ warble executable gemjar war
mkdir -p tmp
rm -f tmp/gems.jar
Creating tmp/gems.jar
rm -f jruby_on_rails.war
Creating jruby_on_rails.war
config

Generates a config/warble.rb configuration file for advanced configuration.

Advanced configuration

The config/warble.rb file provides very precise configuration of the .war build process. You have the power to change what files are included, manage Java and Gem dependencies, customize the web.xml file, configure Rack, and control the number of JRuby runtimes used.

# Disable automatic framework detection by uncommenting/setting to false
# Warbler.framework_detection = false

# Warbler web application assembly configuration file
Warbler::Config.new do |config|
  # Features: additional options controlling how the jar is built.
  # Currently the following features are supported:
  # - gemjar: package the gem repository in a jar file in WEB-INF/lib
  # config.features = %w(gemjar)

  # Application directories to be included in the webapp.
  config.dirs = %w(app config lib log vendor tmp)

  # Additional files/directories to include, above those in config.dirs
  # config.includes = FileList["db"]

  # Additional files/directories to exclude
  # config.excludes = FileList["lib/tasks/*"]

  # Additional Java .jar files to include.  Note that if .jar files are placed
  # in lib (and not otherwise excluded) then they need not be mentioned here.
  # JRuby and JRuby-Rack are pre-loaded in this list.  Be sure to include your
  # own versions if you directly set the value
  # config.java_libs += FileList["lib/java/*.jar"]

  # Loose Java classes and miscellaneous files to be placed in WEB-INF/classes.
  # config.java_classes = FileList["target/classes/**.*"]

  # One or more pathmaps defining how the java classes should be copied into
  # WEB-INF/classes. The example pathmap below accompanies the java_classes
  # configuration above. See http://rake.rubyforge.org/classes/String.html#M000017
  # for details of how to specify a pathmap.
  # config.pathmaps.java_classes << "%{target/classes/,}p"

  # Path to the pre-bundled gem directory inside the war file. Default
  # is 'WEB-INF/gems'. Specify path if gems are already bundled
  # before running Warbler. This also sets 'gem.path' inside web.xml.
  # config.gem_path = "WEB-INF/vendor/bundler_gems"

  # Bundler support is built-in. If Warbler finds a Gemfile in the
  # project directory, it will be used to collect the gems to bundle
  # in your application. If you wish to explicitly disable this
  # functionality, uncomment here.
  # config.bundler = false

  # Files for WEB-INF directory (next to web.xml). This contains
  # web.xml by default. If there is an .erb-File it will be processed
  # with webxml-config. You may want to exclude this file via
  # config.excludes.
  # config.webinf_files += FileList["jboss-web.xml"]

  # Other gems to be included. You need to tell Warbler which gems
  # your application needs so that they can be packaged in the war
  # file.
  # The Rails gems are included by default unless the vendor/rails
  # directory is present.
  # config.gems += ["activerecord-jdbcmysql-adapter", "jruby-openssl"]
  # config.gems << "tzinfo"

  # Uncomment this if you don't want to package rails gem.
  # config.gems -= ["rails"]

  # The most recent versions of gems are used.
  # You can specify versions of gems by using a hash assignment:
  # config.gems["rails"] = "2.0.2"

  # You can also use regexps or Gem::Dependency objects for flexibility or
  # fine-grained control.
  # config.gems << /^merb-/
  # config.gems << Gem::Dependency.new("merb-core", "= 0.9.3")

  # Include gem dependencies not mentioned specifically. Default is true, uncomment
  # to turn off.
  # config.gem_dependencies = false

  # Files to be included in the root of the webapp.  Note that files in public
  # will have the leading 'public/' part of the path stripped during staging.
  # config.public_html = FileList["public/**/*", "doc/**/*"]

  # Pathmaps for controlling how public HTML files are copied into the .war
  # config.pathmaps.public_html = ["%{public/,}p"]

  # Pathmaps for controlling how application files are copied into the .war
  # config.pathmaps.application = ["WEB-INF/%p"]

  # Name of the war file (without the .war) -- defaults to the basename
  # of RAILS_ROOT
  # config.war_name = "mywar"

  # Name of the MANIFEST.MF template for the war file. Defaults to the
  # MANIFEST.MF normally generated by `jar cf`.
  # config.manifest_file = "config/MANIFEST.MF"

  # Value of RAILS_ENV for the webapp -- default as shown below
  # config.webxml.rails.env = ENV['RAILS_ENV'] || 'production'

  # Application booter to use, one of :rack, :rails, or :merb (autodetected by default)
  # config.webxml.booter = :rails

  # When using the :rack booter, "Rackup" script to use.
  # - For 'rackup.path', the value points to the location of the rackup
  # script in the web archive file. You need to make sure this file
  # gets included in the war, possibly by adding it to config.includes
  # or config.webinf_files above.
  # - For 'rackup', the rackup script you provide as an inline string
  #   is simply embedded in web.xml.
  # The script is evaluated in a Rack::Builder to load the application.
  # Examples:
  # config.webxml.rackup.path = 'WEB-INF/hello.ru'
  # config.webxml.rackup = %{require './lib/demo'; run Rack::Adapter::Camping.new(Demo)}
  # config.webxml.rackup = require 'cgi' && CGI::escapeHTML(File.read("config.ru"))

  # Control the pool of Rails runtimes. Leaving unspecified means
  # the pool will grow as needed to service requests. It is recommended
  # that you fix these values when running a production server!
  # config.webxml.jruby.min.runtimes = 2
  # config.webxml.jruby.max.runtimes = 4

  # JNDI data source name
  # config.webxml.jndi = 'jdbc/rails'
end
Site last updated on: February 4, 2012 at 11:31:56 AM PST
Cover for Rails 3 in a Nutshell

View 1 comment

  1. L. BUCKLAND – Posted Oct. 26, 2011

    "step" should be plural, "steps"

Add a comment

View 1 comment

  1. L. BUCKLAND – Posted Oct. 26, 2011

    Edit to read "... is configured to avoid actually sending any email messages."

Add a comment

View 1 comment

  1. L. BUCKLAND – Posted Oct. 26, 2011

    It would be helpful to note that these are two versions of the same command.

Add a comment

View 1 comment

  1. bananastalktome – Posted May 20, 2010

    Might be worth mentioning the use of a mongrel cluster as a substitute for passenger, since some systems do not play well with passenger (eg. Solaris).

Add a comment

 
customer-service@oreilly.com

©2011, O'Reilly Media, Inc.
All trademarks and registered trademarks appearing on oreilly.com are the property of their respective owners.