You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by wo...@apache.org on 2018/04/12 20:09:43 UTC

[couchdb-documentation] branch nginx updated (a6c1fbf -> 40d7c30)

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

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


    omit a6c1fbf  Add nginx docs
     add 4389cf5  Bump curl earlier in intro, fix for Windows
     new 40d7c30  Add nginx docs

This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version.  This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:

 * -- * -- B -- O -- O -- O   (a6c1fbf)
            \
             N -- N -- N   refs/heads/nginx (40d7c30)

You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.

Any revisions marked "omit" are not gone; other references still
refer to them.  Any revisions marked "discard" are gone forever.

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 src/intro/curl.rst  | 20 ++++++++++++++++++++
 src/intro/index.rst |  2 +-
 2 files changed, 21 insertions(+), 1 deletion(-)

-- 
To stop receiving notification emails like this one, please contact
wohali@apache.org.

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

Posted by wo...@apache.org.
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 <jo...@atypical.net>
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 0000000..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
+``<nginx config directory>/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;
+        proxy_set_header Host $host;
+        proxy_buffering off;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Ssl on;
+    }
+
+The ``X-Forwarded-Ssl`` header tells CouchDB that it should use the ``https``
+scheme instead of the ``http`` scheme. Otherwise, all CouchDB-generated
+redirects will fail.

-- 
To stop receiving notification emails like this one, please contact
wohali@apache.org.