(tutorial) rackup howto

rackup How-To

By Sam Roberts

Config File Syntax

The config file is config.ru if none is specified.

Handling of config files depends on whether it’s .ru, or something else. It’s important to define the application that rackup will run correctly; failure to do so will result in mysterious runtime errors!

With a .ru config file

The config file is treated as if it is the body of

app = Rack::Builder.new { … config_file_content_here … }.to_app  

Also, the first line starting with #\ is treated as if it were command-line options, allowing rackup arguments to be specified in the config file. For example:

#\ -w -p 8765  
use Rack::Reloader, 0  
use Rack::ContentLength

app = proc do |env|  
  [200, {'Content-Type' => 'text/plain'}, ['a']]
end

run app  

Would run with Ruby warnings enabled, and request port 8765.

(Detail: the -p option will be ignored unless the server supports the :Port option.)

With a .rb, etc config file

The config file is required. It must assign the app to a global constant so rackup can find it.

The name of the constant should be config file’s base name, stripped of a trailing .rb (if present), and capitalized. The following config files all look for Config:

• ~/bin/config
• config.rb
• /usr/bin/config
• example/config.rb

This will work if the file name is octet.rb:

Octet = Rack::Builder.new do  
  use Rack::Reloader, 0
  use Rack::ContentLength  
  app = proc do |env|
    [ 200, { 'Content-Type' => 'text/plain' }, ['b']]
  end  
  run app  
end.to_app  

Auto-Selection of a Server

The specified server (from Handler.get) is used, or the first of these to match is selected:

• PHP_FCGI_CHILDREN is in the process environment, use FastCGI
• REQUEST_METHOD is in the process environment, use CGI
• If Puma is installed, use that
• If Thin is installed, use that
• If falcon is installed, use that
• Otherwise, use WEBRick

Automatic Middleware

rackup will automatically use some middleware, depending on the environment you select, the -E switch, with development being the default:

• development: CommonLogger, ShowExceptions, Lint
• deployment: CommonLogger
• none: none

CommonLogger isn’t used with the CGI server, because it writes to stderr, which doesn’t interact so well with CGI.