`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
Rack::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.

rackup How-To