Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mdirolf/nginx-gridfs

Nginx module for serving files from MongoDB's GridFS
https://github.com/mdirolf/nginx-gridfs

Last synced: 12 days ago
JSON representation

Nginx module for serving files from MongoDB's GridFS

Awesome Lists containing this project

README 

        
nginx-gridfs

============

:Authors:

    Mike Dirolf ,

    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 `_ module to serve

content directly from `MongoDB `_'s `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 `_ 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.