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/08/14 21:58:34 UTC
[couchdb-documentation] branch master updated: Add Caddy Server
reverse-proxy config examples incl. cluster load balancing (#318)
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 ad92f4a Add Caddy Server reverse-proxy config examples incl. cluster load balancing (#318)
ad92f4a is described below
commit ad92f4a398212f921fcbf3ae51909646133de57a
Author: Dave Willenberg <da...@detroit-english.de>
AuthorDate: Tue Aug 14 23:58:32 2018 +0200
Add Caddy Server reverse-proxy config examples incl. cluster load balancing (#318)
* Merge nginx and caddy into single 'Reverse Proxies' section
* Add Caddy reverse-proxy configs with example for cluster load balancing
---
src/best-practices/index.rst | 2 +-
src/best-practices/nginx.rst | 125 ---------------
src/best-practices/reverse-proxies.rst | 269 +++++++++++++++++++++++++++++++++
3 files changed, 270 insertions(+), 126 deletions(-)
diff --git a/src/best-practices/index.rst b/src/best-practices/index.rst
index 53aada3..c19032d 100644
--- a/src/best-practices/index.rst
+++ b/src/best-practices/index.rst
@@ -27,4 +27,4 @@ system.
documents
forms
jsdevel
- nginx
+ reverse-proxies
diff --git a/src/best-practices/nginx.rst b/src/best-practices/nginx.rst
deleted file mode 100644
index 91d9885..0000000
--- a/src/best-practices/nginx.rst
+++ /dev/null
@@ -1,125 +0,0 @@
-.. 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.
diff --git a/src/best-practices/reverse-proxies.rst b/src/best-practices/reverse-proxies.rst
new file mode 100644
index 0000000..051e7f5
--- /dev/null
+++ b/src/best-practices/reverse-proxies.rst
@@ -0,0 +1,269 @@
+.. 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/reverse-proxies:
+
+========================
+Reverse Proxies
+========================
+
+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, there are suitable alternatives. Below are examples for
+configuring nginx and Caddy web-servers appropriately.
+
+.. _HAProxy: http://haproxy.org/
+.. _code repository: https://github.com/apache/couchdb/blob/master/rel/haproxy.cfg
+
+Reverse proxying with nginx
+===========================
+
+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;
+ }
+
+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.
+
+Reverse Proxying with Caddy
+===========================
+
+Basic configuration
+-------------------
+
+Here's a basic excerpt from a Caddyfile in
+``/<path>/<to>/<site>/Caddyfile``. This will proxy all
+requests from ``http(s)://domain.com/...`` to ``http://localhost:5984/...``
+
+.. code-block:: text
+
+ domain.com {
+
+ import /path/to/other/config.caddy # logging, error handling etc.
+
+ proxy / localhost:5984 {
+ transparent
+ }
+
+ }
+
+.. Note::
+ The ``transparent`` preset in the ``proxy`` directive is shorthand for:
+
+ .. code-block:: text
+
+ header_upstream Host {host}
+ header_upstream X-Real-IP {remote}
+ header_upstream X-Forwarded-For {remote}
+ header_upstream X-Forwarded-Proto {scheme}
+
+Note that, because Caddy is https-by-default, you must explicitly include the
+``http://`` protocol in the site address if you do NOT want Caddy
+to automatically acquire and install an SSL certificate and begin accepting
+``https`` connections on port 443.
+
+Reverse proxying CouchDB in a subdirectory with Caddy
+-----------------------------------------------------
+
+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 Caddy
+configuration that proxies the URL ``http(s)://domain.com/couchdb`` to
+``http://localhost:5984`` so that requests appended to the subdirectory, such
+as ``http(s)://domain.com/couchdb/db1/doc1`` are proxied to
+``http://localhost:5984/db1/doc1``.
+
+.. code-block:: text
+
+ domain.com {
+
+ import /path/to/other/config.caddy # logging, error handling etc.
+
+ proxy /couchdb localhost:5984 {
+ transparent
+ without /couchdb
+ }
+
+ }
+
+Reverse proxying + load balancing for CouchDB clusters
+------------------------------------------------------
+
+Here's a basic excerpt from a Caddyfile in
+``/<path>/<to>/<site>/Caddyfile``. This will proxy and evenly distribute all
+requests from ``http(s)://domain.com/...`` among 3 CouchDB cluster nodes
+at ``localhost:15984``, ``localhost:25984`` and ``localhost:35984``.
+
+Caddy will check the status, i.e. health, of each node every 5 seconds;
+if a node goes down, Caddy will avoid proxying requests to that node until it
+comes back online.
+
+.. code-block:: text
+
+ domain.com {
+
+ import /path/to/other/config.caddy # logging, error handling etc.
+
+ proxy / http://localhost:15984 http://localhost:25984 http://localhost:35984 {
+ policy round_robin
+ health_check /_up
+ health_check_duration 5s
+ try_interval 500ms
+ keepalive 0
+ transparent
+ }
+
+ }
+
+Authentication with Caddy as a reverse proxy
+--------------------------------------------
+
+Here's a sample config setting with basic authentication enabled, placing
+CouchDB in the ``/couchdb`` subdirectory:
+
+.. code-block:: text
+
+ domain.com {
+
+ import /path/to/other/config.caddy # logging, error handling etc.
+
+ basicauth /couchdb couch_username couchdb_password
+
+ proxy /couchdb localhost:5984 {
+ transparent
+ header_upstream -Authorization
+ without /couchdb
+ }
+
+ }
+
+For security reasons, using a plaintext password in the ``Caddyfile`` is not
+advisable. One solution is to define Caddy-process environment variables e.g.
+``COUCH_PW=couchdb_password`` and using placeholders in the ``Caddyfile``
+instead, e.g. ``{$COUCH_PW}``.
+
+This setup leans entirely on Caddy 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/TLS with Caddy
+------------------
+
+Caddy is https-by-default, and will automatically acquire, install, activate and,
+when necessary, renew a trusted SSL certificate for you - all in the background.
+Certificates are issued by the LetsEncrypt certificate authority.
+
+.. code-block:: text
+
+ domain.com {
+
+ import /path/to/other/config.caddy # logging, error handling etc.
+
+ proxy / localhost:5984 {
+ transparent
+ header_upstream 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.