oddjob

oddjob is a lightweight, command line controlled web server. Built for development and testing purposes, it can be used to serve static content for local web development and has basic file upload capabilities. It was initially created when web browsers become more restrictive about displaying local files directly (i.e. file:// URLs).

oddjob's file upload endpoint can be used directly via forms or ajax request you build yourself with a POST to the /oj_upload URL. A basic file upload form is also available via a GET request to that same URL. Upon upload the default behaviour is for the server to dump the entire upload POST request (header and body), followed by the contents of each uploaded file to STDOUT. This is useful for small tests uploading text files, but if you need to upload larger or binary format files tell oddjob to save the files to a directory instead. If you upload and save the same file twice oddjob will not overwrite existing saved files, instead a unique name is generated by adding a number to the end of the file's name.

It is easy to hack the oddjob script to build quick test jigs for web development. Sometimes using a simple test web server is easier than working with a full fledged development or production environment. To hack the code download from the github repo and run oddjob out of the included bin directory.

Installation

oddjob is available as a ruby gem. To install it for general command line use gem install:

gem install oddjob

In the unlikely event you would like it tied to a project add the following line to the project's Gemfile:

gem 'oddjob'

And then execute:

bundle install

You can also run oddjob directly from the git repo. Clone the git repo and run oddjob directly from the repo's bin directory. For example:

git clone https://github.com/MCF/oddjob.git
./oddjob/bin/oddjob

Usage

Command line usage is:

oddjob [OPTIONS] [server_root]

Where the optional server_root argument will be the served root directory. The default server root is the current working directory.

The default file upload behaviour will print the contents of the HTTP POST request, and the contents of any uploaded files, to the server's STDOUT. It is recommended that you only upload text files in this case. If an output directory is specified all uploaded files are saved under their own names in this directory. Pre-existing files are not overwritten, instead a number is added to the end of the new file names when saving.

If a simulated network delay is specified the server will pause that many seconds before returning a response for file(s) uploaded to the file upload path: /oj_upload.

The server will only respond to clients on localhost unless the --allhosts option is specified. Be aware of the security implications of allowing any other host on your network to connect to the server if you use this option.

An informational page is available at the /oj_info path that includes the command line usage.

The default server port is 4400.

Command line options:

-d, --delay=value                File upload simulated network delay
-a, --allhosts                   Allow connections from all hosts
-o, --output=value               Directory to save uploaded files
-p, --port=value                 Web server port to use
    --version                    Display the version number and exit

-h, --help                       Display the usage message

To stop oddjob use the normal interrupt key combination (usually Ctrl-C).

Examples

oddjob

Serves the files and directories in your current working directory at http://localhost:4400/. File upload is available at http://localhost:4400/oj_upload

oddjob -p 2222 -o ./uploads ./my-site

Serves the contents of the ./my-site directory at the http://localhost:2222/ URL, file upload is available at http://localhost:2222/oj_upload files are saved to the ./uploads directory.

Environment

oddjob is written in ruby and its only required dependency is a standard ruby install. oddjob makes use of ruby's built in webrick web server library. No gems are required for running oddjob. oddjob has been tested with ruby 1.8.7 and up.

Security

By default oddjob serves to clients on localhost only (that is: browsers running on the same computer as oddjob). If the -a option is used connections from any client on your network are allowed. If you do not trust the users on your local network the -a option could be a security concern. Anyone who can connect to your IP address can browse and download the files served by oddjob.

oddjob will serve the contents of the directory specified on the command line, or the current working directory if no directory is specified. It does no filtering on the contents of the directory served, and the entire directory tree below the top level directory is available for browsing.

License

oddjob is released under an MIT style license.

Development

After checking out the repo, run bundle install to install dependencies. Then, run rake spec to run the tests. Oddjob can be run directly from the repo's bin directory for easy testing.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/MCF/oddjob.