nginx-gridfs

:Authors: Mike Dirolf mike@dirolf.com, Chris Triolo, and everyone listed in the Credits section below

Note from Mike: I'm no longer actively maintaining this project. If you're interested in becoming the new maintainer please shoot me an email.

About

nginx-gridfs is an Nginx <http://nginx.net/> module to serve content directly from MongoDB <http://www.mongodb.org/>'s GridFS <http://www.mongodb.org/display/DOCS/GridFS>_.

Version

The minor version will be incremented with each release until a stable 1.0 is reached. To check out a particular version::

$ git checkout v0.8

Dependencies

nginx-gridfs requires the Mongo-C-Driver which is a submodule to this repository. To check out the submodule (after cloning this repository), run::

$ git submodule init
$ git submodule update

Installation

Installing Nginx modules requires rebuilding Nginx from source:

• Grab the Nginx source <http://nginx.net/>_ and unpack it.
• Clone this repository somewhere on your machine.
• Check out the required submodule, as described above.
• Change to the directory containing the Nginx source.

• Now build::

  $ ./configure --add-module=/path/to/nginx-gridfs/source/ $ make $ make install

Configuration

Directives

gridfs

:syntax: gridfs DB_NAME [root_collection=ROOT] [field=QUERY_FIELD] [type=QUERY_TYPE] [user=USERNAME] [pass=PASSWORD] :default: NONE :context: location

This directive enables the nginx-gridfs module at a given location. The only required parameter is DB_NAME to specify the database to serve files from.

• root_collection= specify the root_collection(prefix) of the GridFS. default: fs
• field= specify the field to query. Supported fields include _id and filename. default: _id
• type= specify the type to query. Supported types include objectid, string and int. default: objectid
• user= specify a username if your mongo database requires authentication. default: NULL
• pass= specify a password if your mongo database requires authentication. default: NULL

mongo

When connecting to a single server::

:syntax: mongo MONGOD_HOST :default: 127.0.0.1:27017 :context: location

When connecting to a replica set::

:syntax: mongo REPLICA_SET_NAME MONGOD_SEED_1 MONGOD_SEED_2 :default: 127.0.0.1:27017 :context: location

This directive specifies a mongod or replica set to connect to. MONGOD_HOST should be in the form of hostname:port. REPLICA_SET_NAME should be the name of the replica set to connect to.

If this directive is not provided, the module will attempt to connect to a MongoDB server at 127.0.0.1:27017.

Sample Configurations

Here is a sample configuration in the relevant section of an nginx.conf::

location /gridfs/ { gridfs my_app; }

This will set up Nginx to serve the file in gridfs with _id ObjectId("a12...") for any request to /gridfs/a12...

Here is another configuration::

location /gridfs/ { gridfs my_app field=filename type=string; mongo 127.0.0.1:27017; }

This will set up Nginx to serve the file in gridfs with filename foo for any request to /gridfs/foo

Here's how to connect to a replica set called "foo" with two seed nodes::

location /gridfs/ { gridfs my_app field=filename type=string; mongo "foo" 10.7.2.27:27017 10.7.2.28:27017; }

Here is another configuration::

location /gridfs/ { gridfs my_app root_collection=pics field=_id type=int user=foo pass=bar; mongo 127.0.0.1:27017; }

This will set up Nginx to communicate with the mongod at 127.0.0.1:27017 and authenticate use of database my_app with username/password combo foo/bar. The gridfs root_collection is specified as pics. Nginx will then serve the file in gridfs with _id 123... for any request to /gridfs/123...

Known Issues / TODO / Things You Should Hack On

• HTTP range support for partial downloads
• Better error handling / logging

Credits

• Sho Fukamachi (sho) - towards compatibility with newer boost versions
• Olivier Bregeras (stunti) - better handling of binary content
• Chris Heald (cheald) - better handling of binary content
• Paul Dlug (pdlug) - mongo authentication
• Todd Zusman (toddzinc) - gzip handling
• Kyle Banker (banker) - replica set support

License

nginx-gridfs is dual licensed under the Apache License, Version 2.0 and the GNU General Public License, either version 2 or (at your option) any later version. See LICENSE for details.