This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new 1d9ce5c More how tos (#371)
1d9ce5c is described below
commit 1d9ce5cfa908ed30ee82b7eee6864d1768a69c61
Author: Joan Touzet <woh...@users.noreply.github.com>
AuthorDate: Thu Dec 20 11:30:55 2018 -0500
More how tos (#371)
* Typos and fixes from @flimzy review
* Migrated Apache as a reverse proxy from MoinMoin; called out HAProxy more
prominently
* Adding pointer to more Erlang query server examples
* Add link to video on vhost/rewrite behaviour
---
Makefile | 2 +-
src/best-practices/documents.rst | 9 ++--
src/best-practices/reverse-proxies.rst | 87 ++++++++++++++++++++++++++++++++--
src/config/http.rst | 4 ++
src/config/query-servers.rst | 3 ++
5 files changed, 96 insertions(+), 9 deletions(-)
diff --git a/Makefile b/Makefile
index 62d75e2..d9b157a 100644
--- a/Makefile
+++ b/Makefile
@@ -45,7 +45,7 @@ man: $(SPHINXBUILD)
$(SPHINXBUILD) -b $@ $(SPHINXOPTS) $(BUILDDIR)/$@
check:
- python ext/linter.py $(SOURCE)
+ python3 ext/linter.py $(SOURCE)
install-html:
install-pdf:
diff --git a/src/best-practices/documents.rst b/src/best-practices/documents.rst
index 6230679..9cc181c 100644
--- a/src/best-practices/documents.rst
+++ b/src/best-practices/documents.rst
@@ -141,8 +141,7 @@ periodically, and are disconnected for more than this time
before they
resynchronise.
All of the approaches below which allow automated merging of changes rely on
-having some sort of history back in time to the point where the replicas
-diverged.
+having some sort of history, back to the point where the replicas diverged.
CouchDB does not provide a mechanism for this itself. It stores arbitrary
numbers of old _ids for one document (trunk now has a mechanism for pruning the
@@ -160,7 +159,7 @@ live replicas last diverged.
Approach 1: Single JSON doc
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The above structure is already valid Javascript, and so could be represented in
+The above structure is already valid JSON, and so could be represented in
CouchDB just by wrapping it in an object and storing as a single document:
.. code-block:: javascript
@@ -328,8 +327,8 @@ layer on the database to test each transaction. Some
advantages are:
* Only the client or someone with the knowledge of the name and password can
compute
the value of SHA256 and recover the data.
-* Some columns are still left in the clear, an advantage if the marketing
department
- wants to compute aggregated statistics.
+* Some columns are still left in the clear, an advantage for computing
aggregated
+ statistics.
* Computation of SHA256 is left to the client side computer which usually has
cycles
to spare.
* The system prevents server-side snooping by insiders and any attacker who
might
diff --git a/src/best-practices/reverse-proxies.rst
b/src/best-practices/reverse-proxies.rst
index 051e7f5..5105960 100644
--- a/src/best-practices/reverse-proxies.rst
+++ b/src/best-practices/reverse-proxies.rst
@@ -16,15 +16,54 @@
Reverse Proxies
========================
+Reverse proxying with HAProxy
+=============================
+
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``.
+release tarball as ``rel/haproxy.cfg``. It is included below. This example
+is for a 3 node CouchDB cluster:
+
+.. code-block:: text
-However, there are suitable alternatives. Below are examples for
-configuring nginx and Caddy web-servers appropriately.
+ global
+ maxconn 512
+ spread-checks 5
+
+ defaults
+ mode http
+ log global
+ monitor-uri /_haproxy_health_check
+ option log-health-checks
+ option httplog
+ balance roundrobin
+ option forwardfor
+ option redispatch
+ retries 4
+ option http-server-close
+ timeout client 150000
+ timeout server 3600000
+ timeout connect 500
+
+ stats enable
+ stats uri /_haproxy_stats
+ # stats auth admin:admin # Uncomment for basic auth
+
+ frontend http-in
+ # This requires HAProxy 1.5.x
+ # bind *:$HAPROXY_PORT
+ bind *:5984
+ default_backend couchdbs
+
+ backend couchdbs
+ option httpchk GET /_up
+ http-check disable-on-404
+ server couchdb1 x.x.x.x:5984 check inter 5s
+ server couchdb2 x.x.x.x:5984 check inter 5s
+ server couchdb2 x.x.x.x:5984 check inter 5s
.. _HAProxy: http://haproxy.org/
.. _code repository:
https://github.com/apache/couchdb/blob/master/rel/haproxy.cfg
@@ -267,3 +306,45 @@ Certificates are issued by the LetsEncrypt certificate
authority.
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.
+
+Reverse Proxying with Apache HTTP Server
+========================================
+
+.. warning::
+ As of this writing, there is no way to fully disable the buffering between
+ Apache HTTPD Server and CouchDB. This may present problems with continuous
+ replication. The Apache CouchDB team strongly recommend the use of an
+ alternative reverse proxy such as ``haproxy`` or ``nginx``, as described
+ earlier in this section.
+
+Basic Configuration
+-------------------
+
+Here's a basic excerpt for using a ``VirtualHost`` block config to use Apache
+as a reverse proxy for CouchDB. You need at least to configure Apache with the
+``--enable-proxy --enable-proxy-http`` options and use a version equal to or
+higher than Apache 2.2.7 in order to use the ``nocanon`` option in the
+``ProxyPass`` directive. The ``ProxyPass`` directive adds the
``X-Forwarded-For``
+header needed by CouchDB, and the ``ProxyPreserveHost`` directive ensures the
+original client ``Host`` header is preserved.
+
+.. code-block:: apacheconf
+
+ <VirtualHost *:80>
+ ServerAdmin webmas...@dummy-host.example.com
+ DocumentRoot "/opt/websites/web/www/dummy"
+ ServerName couchdb.localhost
+ AllowEncodedSlashes On
+ ProxyRequests Off
+ KeepAlive Off
+ <Proxy *>
+ Order deny,allow
+ Deny from all
+ Allow from 127.0.0.1
+ </Proxy>
+ ProxyPass / http://localhost:5984 nocanon
+ ProxyPassReverse / http://localhost:5984
+ ProxyPreserveHost On
+ ErrorLog "logs/couchdb.localhost-error_log"
+ CustomLog "logs/couchdb.localhost-access_log" common
+ </VirtualHost>
diff --git a/src/config/http.rst b/src/config/http.rst
index 87f30a8..aa38009 100644
--- a/src/config/http.rst
+++ b/src/config/http.rst
@@ -606,6 +606,10 @@ with the vhost name prefixed by ``cors:``. Example case
for the vhost
; List of accepted methods
methods = HEAD, GET
+A video from 2010 on vhost and rewrite configuration `is available
+<https://vimeo.com/20773112>`_, but is not guaranteed to match current syntax
+or behaviour.
+
.. _config/vhosts:
Virtual Hosts
diff --git a/src/config/query-servers.rst b/src/config/query-servers.rst
index 8032820..40a18aa 100644
--- a/src/config/query-servers.rst
+++ b/src/config/query-servers.rst
@@ -186,3 +186,6 @@ Native Erlang Query Server
If all has gone well, after running the view you should see a list of the
total number of documents at each revision number.
+
+ Additional examples are on the `us...@couchdb.apache.org mailing list
+
<https://lists.apache.org/thread.html/9b5f2837bd32189385bb82eee44aec243f2ecacc6e907ffe0e1e03d3@1360091211@%3Cuser.couchdb.apache.org%3E>`_.
