[couchdb-documentation] 01/01: Add nginx docs

[wohali]

This is an automated email from the ASF dual-hosted git repository.

wohali pushed a commit to branch nginx
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 40d7c30d97a13444755261e02bfac2accfbbcd95
Author: Joan Touzet 
AuthorDate: Thu Apr 12 13:26:09 2018 -0400

Add nginx docs
---
 src/best-practices/index.rst |   1 +
 src/best-practices/nginx.rst | 125 +++
 2 files changed, 126 insertions(+)

diff --git a/src/best-practices/index.rst b/src/best-practices/index.rst
index 0ea8c7a..362b3f1 100644
--- a/src/best-practices/index.rst
+++ b/src/best-practices/index.rst
@@ -26,3 +26,4 @@ system.
 
 forms
 jsdevel
+nginx
diff --git a/src/best-practices/nginx.rst b/src/best-practices/nginx.rst
new file mode 100644
index 000..91d9885
--- /dev/null
+++ b/src/best-practices/nginx.rst
@@ -0,0 +1,125 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _best-practices/nginx:
+
+
+nginx as a Reverse Proxy
+
+
+CouchDB recommends the use of `HAProxy`_ as a load balancer and reverse proxy.
+The team's experience with using it in production has shown it to be superior
+for configuration and montioring capabilities, as well as overall performance.
+
+CouchDB's sample haproxy configuration is present in the `code repository`_ and
+release tarball as ``rel/haproxy.cfg``.
+
+However, ``nginx`` is a suitable alternative. Below are instructions on
+configuring nginx appropriately.
+
+.. _HAProxy: http://haproxy.org/
+.. _code repository: 
https://github.com/apache/couchdb/blob/master/rel/haproxy.cfg
+
+Basic configuration
+===
+
+Here's a basic excerpt from an nginx config file in
+``/sites-available/default``. This will proxy all
+requests from ``http://domain.com/...`` to ``http://localhost:5984/...``
+
+.. code-block:: text
+
+location / {
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_buffering off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+Proxy buffering **must** be disabled, or continuous replication will not
+function correctly behind nginx.
+
+Reverse proxying CouchDB in a subdirectory with nginx
+=
+
+It can be useful to provide CouchDB as a subdirectory of your overall domain,
+especially to avoid CORS concerns. Here's an excerpt of a basic nginx
+configuration that proxies the URL ``http://domain.com/couchdb`` to
+``http://localhost:5984`` so that requests appended to the subdirectory, such
+as ``http://domain.com/couchdb/db1/doc1`` are proxied to
+``http://localhost:5984/db1/doc1``.
+
+.. code-block:: text
+
+location /couchdb {
+rewrite /couchdb/(.*) /$1 break;
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_buffering off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+Note that in the above configuration, the *Verify Installation* link in
+Fauxton may not succeed.
+
+Authentication with nginx as a reverse proxy
+
+
+Here's a sample config setting with basic authentication enabled, placing
+CouchDB in the ``/couchdb`` subdirectory:
+
+.. code-block:: text
+
+location /couchdb {
+auth_basic "Restricted";
+auth_basic_user_file htpasswd;
+rewrite /couchdb/(.*) /$1 break;
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_buffering off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header Authorization "";
+}
+
+This setup leans entirely on nginx performing authorization, and forwarding
+requests to CouchDB with no authentication (with CouchDB in Admin Party mode).
+For a better solution, see :ref:`api/auth/proxy`.
+
+SSL with nginx
+==
+
+In order to enable SSL, just enable the nginx SSL module, and add another
+proxy header:
+
+.. code-block:: text
+
+ssl on;
+ssl_certificate PATH_TO_YOUR_PUBLIC_KEY.pem;
+ssl_certificate_key PATH_TO_YOUR_PRIVATE_KEY.key;
+ssl_protocols SSLv3;
+ssl_session_cache shared:SSL:1m;
+
+location / {
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+

[couchdb-documentation] 01/01: Add nginx docs

[wohali]

This is an automated email from the ASF dual-hosted git repository.

wohali pushed a commit to branch nginx
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit a6c1fbfaf27c91d4aaebcf156ac6fa143a3bf238
Author: Joan Touzet 
AuthorDate: Thu Apr 12 13:26:09 2018 -0400

Add nginx docs
---
 src/best-practices/index.rst |   1 +
 src/best-practices/nginx.rst | 125 +++
 2 files changed, 126 insertions(+)

diff --git a/src/best-practices/index.rst b/src/best-practices/index.rst
index 0ea8c7a..362b3f1 100644
--- a/src/best-practices/index.rst
+++ b/src/best-practices/index.rst
@@ -26,3 +26,4 @@ system.
 
 forms
 jsdevel
+nginx
diff --git a/src/best-practices/nginx.rst b/src/best-practices/nginx.rst
new file mode 100644
index 000..91d9885
--- /dev/null
+++ b/src/best-practices/nginx.rst
@@ -0,0 +1,125 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _best-practices/nginx:
+
+
+nginx as a Reverse Proxy
+
+
+CouchDB recommends the use of `HAProxy`_ as a load balancer and reverse proxy.
+The team's experience with using it in production has shown it to be superior
+for configuration and montioring capabilities, as well as overall performance.
+
+CouchDB's sample haproxy configuration is present in the `code repository`_ and
+release tarball as ``rel/haproxy.cfg``.
+
+However, ``nginx`` is a suitable alternative. Below are instructions on
+configuring nginx appropriately.
+
+.. _HAProxy: http://haproxy.org/
+.. _code repository: 
https://github.com/apache/couchdb/blob/master/rel/haproxy.cfg
+
+Basic configuration
+===
+
+Here's a basic excerpt from an nginx config file in
+``/sites-available/default``. This will proxy all
+requests from ``http://domain.com/...`` to ``http://localhost:5984/...``
+
+.. code-block:: text
+
+location / {
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_buffering off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+Proxy buffering **must** be disabled, or continuous replication will not
+function correctly behind nginx.
+
+Reverse proxying CouchDB in a subdirectory with nginx
+=
+
+It can be useful to provide CouchDB as a subdirectory of your overall domain,
+especially to avoid CORS concerns. Here's an excerpt of a basic nginx
+configuration that proxies the URL ``http://domain.com/couchdb`` to
+``http://localhost:5984`` so that requests appended to the subdirectory, such
+as ``http://domain.com/couchdb/db1/doc1`` are proxied to
+``http://localhost:5984/db1/doc1``.
+
+.. code-block:: text
+
+location /couchdb {
+rewrite /couchdb/(.*) /$1 break;
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_buffering off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+Note that in the above configuration, the *Verify Installation* link in
+Fauxton may not succeed.
+
+Authentication with nginx as a reverse proxy
+
+
+Here's a sample config setting with basic authentication enabled, placing
+CouchDB in the ``/couchdb`` subdirectory:
+
+.. code-block:: text
+
+location /couchdb {
+auth_basic "Restricted";
+auth_basic_user_file htpasswd;
+rewrite /couchdb/(.*) /$1 break;
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_buffering off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header Authorization "";
+}
+
+This setup leans entirely on nginx performing authorization, and forwarding
+requests to CouchDB with no authentication (with CouchDB in Admin Party mode).
+For a better solution, see :ref:`api/auth/proxy`.
+
+SSL with nginx
+==
+
+In order to enable SSL, just enable the nginx SSL module, and add another
+proxy header:
+
+.. code-block:: text
+
+ssl on;
+ssl_certificate PATH_TO_YOUR_PUBLIC_KEY.pem;
+ssl_certificate_key PATH_TO_YOUR_PRIVATE_KEY.key;
+ssl_protocols SSLv3;
+ssl_session_cache shared:SSL:1m;
+
+location / {
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+

[couchdb-documentation] 01/01: Add nginx docs

[wohali]

This is an automated email from the ASF dual-hosted git repository.

wohali pushed a commit to branch nginx
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit bc1de63585a917ac4b8e6b622f0319542d5dab2d
Author: Joan Touzet 
AuthorDate: Thu Apr 12 13:26:09 2018 -0400

Add nginx docs
---
 src/best-practices/index.rst |   1 +
 src/best-practices/nginx.rst | 134 +++
 2 files changed, 135 insertions(+)

diff --git a/src/best-practices/index.rst b/src/best-practices/index.rst
index 0ea8c7a..362b3f1 100644
--- a/src/best-practices/index.rst
+++ b/src/best-practices/index.rst
@@ -26,3 +26,4 @@ system.
 
 forms
 jsdevel
+nginx
diff --git a/src/best-practices/nginx.rst b/src/best-practices/nginx.rst
new file mode 100644
index 000..989f0b9
--- /dev/null
+++ b/src/best-practices/nginx.rst
@@ -0,0 +1,134 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy 
of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations 
under
+.. the License.
+
+.. _best-practices/nginx:
+
+
+nginx as a Reverse Proxy
+
+
+CouchDB recommends the use of `HAProxy`_ as a load balancer and reverse proxy.
+The team's experience with using it in production has shown it to be superior
+for configuration and montioring capabilities, as well as overall performance.
+
+CouchDB's sample haproxy configuration is present in the `code repository`_ and
+release tarball as ``rel/haproxy.cfg``.
+
+However, ``nginx`` is a suitable alternative. Below are instructions on
+configuring nginx appropriately.
+
+.. _HAProxy: http://haproxy.org/
+.. _code repository: 
https://github.com/apache/couchdb/blob/master/rel/haproxy.cfg
+
+Basic configuration
+===
+
+Here's a basic excerpt from an nginx config file in
+``/sites-available/default``. This will proxy all
+requests from ``http://domain.com/...`` to ``http://localhost:5984/...``
+
+.. code-block:: text
+
+location / {
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+Continuous Replication through nginx
+
+
+The basic configuration above will **not** work correctly when attempting
+continuous replication. To rectify this problem, use the following block:
+
+.. code-block:: text
+
+location ~ ^/(.*)/_changes {
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_buffering off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+Reverse proxying CouchDB in a subdirectory with nginx
+=
+
+It is useful to provide CouchDB as a subdirectory of your overall domain,
+especially to avoid CORS concerns. Here's an excerpt of a basic nginx
+configuration that proxies the URL ``http://domain.com/couchdb`` to
+``http://localhost:5984`` so that requests appended to the subdirectory, such
+as ``http://domain.com/couchdb/db1/doc1`` are proxied to
+``http://localhost:5984/db1/doc1``.
+
+.. code-block:: text
+
+location /couchdb {
+rewrite /couchdb/(.*) /$1 break;
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+Note that in the above configuration, the *Verify Installation* link in
+Fauxton may not succeed.
+
+Authentication with nginx as a reverse proxy
+
+
+Here's a sample config setting with basic authentication enabled, placing
+CouchDB in the ``/couchdb`` subdirectory:
+
+.. code-block:: text
+
+location /couchdb {
+auth_basic "Restricted";
+auth_basic_user_file htpasswd;
+rewrite /couchdb/(.*) /$1 break;
+proxy_pass http://localhost:5984;
+proxy_redirect off;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header Authorization "";
+}
+
+This setup leans entirely on nginx performing authorization, and forwarding
+requests to CouchDB with no authentication (with CouchDB in Admin Party mode).
+For a better solution, see :ref:`api/auth/proxy`.
+
+SSL with nginx
+==
+
+In order to enable SSL, just enable the nginx SSL module, and add another
+proxy header:
+
+.. code-block::