README.rst
1nginx-gridfs
2============
3:Authors:
4 Mike Dirolf <mike@dirolf.com>,
5 Chris Triolo,
6 and everyone listed in the Credits section below
7
8About
9=====
10**nginx-gridfs** is an `Nginx <http://nginx.net/>`_ module to serve
11content directly from `MongoDB <http://www.mongodb.org/>`_'s `GridFS
12<http://www.mongodb.org/display/DOCS/GridFS>`_.
13Added range support.
14
15Version
16============
17
18The minor version will be incremented with each release until
19a stable 1.0 is reached. To check out a particular version::
20
21 $ git checkout v0.8
22
23Dependencies
24============
25**nginx-gridfs** requires the Mongo-C-Driver which is a submodule to
26this repository. To check out the submodule (after cloning this
27repository), run::
28
29 $ git submodule init
30 $ git submodule update
31
32Installation
33============
34Installing Nginx modules requires rebuilding Nginx from source:
35
36* Grab the `Nginx source <http://nginx.net/>`_ and unpack it.
37* Clone this repository somewhere on your machine.
38* Check out the required submodule, as described above.
39* Change to the directory containing the Nginx source.
40* Now build::
41
42 $ ./configure --add-module=/path/to/nginx-gridfs/source/
43 $ make
44 $ make install
45
46Configuration
47=============
48
49Directives
50----------
51
52**gridfs**
53
54:syntax: *gridfs DB_NAME [root_collection=ROOT] [field=QUERY_FIELD] [type=QUERY_TYPE] [user=USERNAME] [pass=PASSWORD]*
55:default: *NONE*
56:context: location
57
58This directive enables the **nginx-gridfs** module at a given location. The
59only required parameter is DB_NAME to specify the database to serve files from.
60
61* *root_collection=* specify the root_collection(prefix) of the GridFS. default: *fs*
62* *field=* specify the field to query. Supported fields include *_id*, *filename* and *md5*. default: *_id*
63* *type=* specify the type to query. Supported types include *objectid*, *string* and *int*. default: *objectid*
64* *user=* specify a username if your mongo database requires authentication. default: *NULL*
65* *pass=* specify a password if your mongo database requires authentication. default: *NULL*
66
67**mongo**
68
69When connecting to a single server::
70
71:syntax: *mongo MONGOD_HOST*
72:default: *127.0.0.1:27017*
73:context: location
74
75When connecting to a replica set::
76
77:syntax: *mongo REPLICA_SET_NAME* *MONGOD_SEED_1* *MONGOD_SEED_2*
78:default: *127.0.0.1:27017*
79:context: location
80
81This directive specifies a mongod or replica set to connect to. MONGOD_HOST should be in the
82form of hostname:port. REPLICA_SET_NAME should be the name of the replica set to connect to.
83
84If this directive is not provided, the module will attempt to connect to a MongoDB server at *127.0.0.1:27017*.
85
86Sample Configurations
87---------------------
88
89Here is a sample configuration in the relevant section of an *nginx.conf*::
90
91 location /gridfs/ {
92 gridfs my_app;
93 }
94
95This will set up Nginx to serve the file in gridfs with _id *ObjectId("a12...")*
96for any request to */gridfs/a12...*
97
98Here is another configuration::
99
100 location /gridfs/ {
101 gridfs my_app field=filename type=string;
102 mongo 127.0.0.1:27017;
103 }
104
105This will set up Nginx to serve the file in gridfs with filename *foo*
106for any request to */gridfs/foo*
107
108Here's how to connect to a replica set called "foo" with two seed nodes::
109
110 location /gridfs/ {
111 gridfs my_app field=filename type=string;
112 mongo "foo"
113 10.7.2.27:27017
114 10.7.2.28:27017;
115 }
116
117Here is another configuration::
118
119 location /gridfs/ {
120 gridfs my_app
121 root_collection=pics
122 field=_id
123 type=int
124 user=foo
125 pass=bar;
126 mongo 127.0.0.1:27017;
127 }
128
129This will set up Nginx to communicate with the mongod at 127.0.0.1:27017 and
130authenticate use of database *my_app* with username/password combo *foo/bar*.
131The gridfs root_collection is specified as *pics*. Nginx will then serve the
132file in gridfs with _id *123...* for any request to */gridfs/123...*
133
134Known Issues / TODO / Things You Should Hack On
135===============================================
136
137* Better error handling / logging
138
139Credits
140=======
141
142* Sho Fukamachi (sho) - towards compatibility with newer boost versions
143* Olivier Bregeras (stunti) - better handling of binary content
144* Chris Heald (cheald) - better handling of binary content
145* Paul Dlug (pdlug) - mongo authentication
146* Todd Zusman (toddzinc) - gzip handling
147* Kyle Banker (banker) - replica set support
148* Liu Pei Pei (lsanotes) - convert to dynamic module
149
150License
151=======
152**nginx-gridfs** is dual licensed under the Apache License, Version
1532.0 and the GNU General Public License, either version 2 or (at your
154option) any later version. See *LICENSE* for details.
155