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.