Serve is a small Rack-based web server and rapid prototyping framework for Web applications (specifically Rails apps). It is designed to compliment web application development and enforce a strict separation of concerns between designer and developer. Using Serve allows the designer to work in a separate prototype project, while the developer ca…
Ruby
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1 commit ahead, 291 commits behind jlong:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
rails
spec
tasks
test_project
.document
.gitignore
CHANGELOG.rdoc
Gemfile
Gemfile.lock
LICENSE
QUICKSTART.rdoc
README.rdoc
Rakefile
VERSION
serve.gemspec

README.rdoc

Serve - A Rapid Prototyping Framework for Web Applications

Serve is a small Rack-based web server that makes it easy to serve HTML, ERB, or HAML from any directory.

But Serve is much more than a simple web server.

Serve's primary purpose is to provide a rapid prototyping framework for Web applications (specifically Rails apps). It is designed to compliment web application development and enforce a strict separation of concerns between designer and developer. Using Serve allows the designer to work in a separate prototype project, while the developer can work on the actual application and utilize resources from the prototype as needed. This allows the designer to focus on presentation and flow, while the developer can focus on implementation.

This “Design First” approach can help a designer identify and fix a large number of problems before a feature is ever touched by the developer. Once a feature has been completed in the prototype project it can also be estimated with a high degree of accuracy.

A Serve prototype can work much like the finished application and be virtually indistinguishable. The only difference being that state is not saved as a user clicks around.

Serve can be used alongside any Web development framework, but Rails developers will find it especially familiar. One way of thinking about Serve is that it is essentially a Rails application with only one part of the Rails MVC stack – the views. Serve basically allows you to have a separate project just for designing the views for the application. When views are ready, they can be copied over from the prototype to the application almost as is. This process is eased since Serve has full support for partials and layouts with either ERB or HAML. Serve can also handle SASS, Textile, and Markdown if the appropriate libraries are installed.

Installation

Serve is distributed as a Ruby gem and can be installed from the command prompt. Just type:

gem install serve

Some systems, like the Mac, may require that you type:

sudo gem install serve

If you are new to the command prompt see:

kb.iu.edu/data/amog.html

You may also want to google “command prompt windows” if you are on a PC or “command prompt osx” if you are on a Mac to find a simple tutorial.

Usage

Once the gem is installed the `serve` command will be available from the command prompt. To launch Serve, just type the command and press enter:

serve

This will launch a simple web server which you can access from any web browser at the following address:

http://localhost:4000

Once the server is going it will output a running log of its activity. To stop the server at any time, type CTRL+C at the command prompt. By default the serve command serves up files from the current directory. To change this behavior, `cd` to the appropriate directory before starting serve or pass the directory as the final parameter to the command:

serve project_directory

The `serve` command automatically binds to 0.0.0.0 (localhost) and uses port 4000 by default. To serve files over a different IP (that is bound to your computer) or port specify those options on the command line:

serve 4000               # a custom port

serve 192.168.1.6        # a custom IP

serve 192.168.1.6:4000   # a custom IP and port

For your convenience if the file “script/server” exists in the current directory the serve command will start that instead of launching a Ruby Web server. You can specify the environment that you want to start the server with as an option on the command line:

serve production         # start script/server in production mode

Rack and Passenger

Advanced users may also want to run Serve as a Rack application. To do this you will need to create a “config.ru” file in the root of your Serve project. Here is an example “config.ru” file:

#\ -p 4000

gem 'activesupport/all'
gem 'serve'

require 'serve'
require 'serve/rack'

# Middleware
use Rack::ShowStatus      # Nice looking 404s and other messages
use Rack::ShowExceptions  # Nice looking errors

# The project root directory
root = ::File.dirname(__FILE__)  

# Rack Application
run Rack::Cascade.new([
  Serve::RackAdapter.new(root),  # Handle ERB, HAML, and other Serve files
  Rack::Directory.new(root)      # Directory listings and everything else
])

Assuming that you have Rack installed, you will then be able to start your application with the `rackup` command. Type `rackup –help` for more information.

If you would like to run Serve as a Rack application with Passenger you will need to create two additional directories: “tmp” and “public”. In the temp directory put an empty “restart.txt” file. In the public directory put your static assets like images and javascripts (anything that does not require special processing by Serve). You may also want to replace the last four lines of “config.ru” with a single reference to the Serve::RackAdapter:

run Serve::RackAdapter.new(root)

By default, Passenger applications serve static assets from the “public” directory so there is no need to use the Rack::Directory application to handle those. If you need directory listings your Web server probably provides something specifically for this purpose and there is no need to rely on Rack for this.

File Types

Serve presently does special processing for files with following extensions:

textile

Evaluates the document as Textile (requires the Redcloth gem)

markdown

Evaluates the document as Markdown (requires the Bluecloth gem)

erb

Experimental support for ERB

haml

Evaluates the document as Haml (requires the Haml gem)

sass

Evaluates the document as Sass (requires the Haml gem)

scss

Evaluates the document as SCSS (requires the Haml gem)

email

Evaluates the document as if it is an e-mail message; the format is identical to a plain/text e-mail message's source

redirect

Redirects to the URL contained in the document

View Helpers

If you drop a file called “view_helpers.rb” in the root of a project, you can define custom helpers for your Haml and ERB views. Just create a ViewHelpers module and define your helper methods there:

module ViewHelpers
  def custom_method
    "Request object: #{request.headers['user-agent']}"
  end
end

Helpers have full access to the request and response objects so you can easily read and manipulate headers.

More Information

You can find more information about Serve, including a detailed Screencast, on the GitHub wiki:

wiki.github.com/jlong/serve

All development takes place on GitHub:

github.com/jlong/serve

License

Serve is released under the MIT license and is copyright © 2007-2010 John W. Long and Adam I. Williams. A copy of the MIT license can be found in the LICENSE file.