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 2016/08/27 07:53:16 UTC
documentation commit: updated refs/heads/master to 1f6633f
Repository: couchdb-documentation
Updated Branches:
refs/heads/master 59edec503 -> 1f6633f30
Importing troubleshooting guide; remove wiki ref
Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/1f6633f3
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/1f6633f3
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/1f6633f3
Branch: refs/heads/master
Commit: 1f6633f304f915e9f376196793340696fca8ce0d
Parents: 59edec5
Author: Joan Touzet <wo...@apache.org>
Authored: Sat Aug 27 03:51:18 2016 -0400
Committer: Joan Touzet <wo...@apache.org>
Committed: Sat Aug 27 03:51:18 2016 -0400
----------------------------------------------------------------------
src/install/index.rst | 1 +
src/install/troubleshooting.rst | 279 +++++++++++++++++++++++++++++++++++
src/install/unix.rst | 24 +--
src/install/windows.rst | 15 --
4 files changed, 283 insertions(+), 36 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/1f6633f3/src/install/index.rst
----------------------------------------------------------------------
diff --git a/src/install/index.rst b/src/install/index.rst
index 419ce63..46a8e6e 100644
--- a/src/install/index.rst
+++ b/src/install/index.rst
@@ -23,3 +23,4 @@ Installation
windows
mac
freebsd
+ troubleshooting
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/1f6633f3/src/install/troubleshooting.rst
----------------------------------------------------------------------
diff --git a/src/install/troubleshooting.rst b/src/install/troubleshooting.rst
new file mode 100644
index 0000000..085b623
--- /dev/null
+++ b/src/install/troubleshooting.rst
@@ -0,0 +1,279 @@
+.. 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.
+
+.. _install/troubleshooting:
+
+===============================
+Troubleshooting an Installation
+===============================
+
+
+First Install
+=============
+
+If your CouchDB doesn't start after you've just installed, check the following
+things:
+
+- On UNIX-like systems, this is usually this is a permissions issue. Ensure
+ that you've followed the :ref:`install/unix/security`
+ ``chown``/``chmod`` commands. This problem is indicated by the presence of
+ the keyword ``eacces`` somewhere in the error output from CouchDB itself.
+- Some Linux distributions split up Erlang into multiple packages. For your
+ distribution, check that you **really** installed all the required Erlang
+ modules. This varies from platform to platform, so you'll just have to
+ work it out for yourself. For example, on recent versions of Ubuntu/Debian,
+ the ``erlang`` package includes all Erlang modules.
+- Confirm that Erlang itself starts up with crypto (SSL) support:
+
+.. code-block:: text
+
+ ## what version of erlang are you running? Ensure it is supported
+ erl -noshell -eval 'io:put_chars(erlang:system_info(otp_release)).' -s erlang halt
+ ## are the erlang crypto (SSL) libraries working?
+ erl -noshell -eval 'case application:load(crypto) of ok -> io:put_chars("yay_crypto\n") ; _ -> exit(no_crypto) end.' -s init stop
+
+- Next, identify where your Erlang CouchDB libraries are installed. This will
+ typically be the lib/ subdirectory of the release that you have installed.
+- Use this to start up Erlang with the CouchDB libraries in its path:
+
+.. code-block:: text
+
+ erl -env ERL_LIBS $ERL_LIBS:/path/to/couchdb/lib -couch_ini -s crypto
+
+- In that Erlang shell, let's check that the key libraries are running. The
+ ``%%`` lines are comments, so you can skip them:
+
+.. code-block:: text
+
+ %% test SSL support. If this fails, ensure you have the OTP erlang-crypto library installed
+ crypto:md5_init().
+
+ %% test Snappy compression. If this fails, check your CouchDB configure script output or alternatively
+ %% if your distro comes with erlang-snappy make sure you're using only the CouchDB supplied version
+ snappy:compress("gogogogogogogogogogogogogogo").
+
+ %% test the CouchDB JSON encoder. CouchDB uses different encoders in each release, this one matches
+ %% what is used in 2.0.x.
+ jiffy:decode(jiffy:encode(<<"[1,2,3,4,5]">>)).
+
+ %% this is how you quit the erlang shell.
+ q().
+
+- The output should resemble this, or an error will be thrown:
+
+.. code-block:: text
+
+ Erlang/OTP 17 [erts-6.2] [source] [64-bit] [smp:2:2] [async-threads:10] [kernel-poll:false]
+
+ Eshell V6.2 (abort with ^G)
+ 1> crypto:md5_init().
+ <<1,35,69,103,137,171,205,239,254,220,186,152,118,84,50,
+ 16,0,0,0,0,0,0,0,0,0,0,0,0,0,...>>
+ 2> snappy:compress("gogogogogogogogogogogogogogo").
+ {ok,<<28,4,103,111,102,2,0>>}
+ 3> jiffy:decode(jiffy:encode(<<"[1,2,3,4,5]">>)).
+ <<"[1,2,3,4,5]">>
+ 4> q().
+
+- At this point the only remaining dependency is your systems' unicode support
+ library, ICU, and the Spidermonkey Javascript VM from Mozilla. Make sure that
+ your ``LD_LIBRARY_PATH`` or similar for non-Linux systems
+ (``DYLD_LIBRARY_PATH`` on macOS) makes these available to CouchDB.
+ Linux example running as normal user:
+
+.. code-block:: text
+
+ LD_LIBRARY_PATH=/usr/local/lib:/usr/local/spidermonkey/lib couchdb
+
+ Linux example running as couchdb user:
+
+.. code-block:: text
+
+ echo LD_LIBRARY_PATH=/usr/local/lib:/usr/local/spidermonkey/lib couchdb | sudo -u couchdb sh
+
+- If you receive an error message including the key word ``eaddrinuse``,
+ such as this:
+
+.. code-block:: text
+
+ Failure to start Mochiweb: eaddrinuse
+
+ edit your ``etc/default.ini`` or ``etc/local.ini`` file and change the
+ ``[chttpd] port = 5984`` line to an available port.
+
+- If you receive an error including the string:
+
+.. code-block:: text
+
+ \u2026 OS Process Error \u2026 {os_process_error,{exit_status,127}}
+
+then it is likely your SpiderMonkey JavaScript VM installation is not
+correct. Please recheck your build dependencies and try again.
+
+- If you receive an error including the string:
+
+.. code-block:: text
+
+ \u2026 OS Process Error \u2026 {os_process_error,{exit_status,139}}
+
+this is caused by the fact that SELinux blocks access to certain areas of
+the filesystem. You must re-configure SELinux, or you can fully disable
+SELinux using the command:
+
+.. code-block:: text
+
+ setenforce 0
+
+- If you are still not able to get CouchDB to start at this point, keep
+ reading.
+
+Quick Build
+===========
+
+Having problems getting CouchDB to run for the first time? Follow this simple
+procedure and report back to the user mailing list or IRC with the output
+of each step. Please put the output of these steps into a paste service (such
+as https://paste.apache.org/) rather than including the output of your entire
+run in IRC or the mailing list directly.
+
+1. Note down the name and version of your operating system and your processor
+ architecture.
+
+2. Note down the installed versions of CouchDB's dependencies.
+
+3. Follow the checkout instructions to get a fresh copy of CouchDB's trunk.
+
+4. Configure from the couchdb directory:
+
+.. code-block:: text
+
+ ./configure
+
+5. Build the release:
+
+.. code-block:: text
+
+ make release
+
+6. Run the couchdb command and log the output:
+
+.. code-block:: text
+
+ cd rel/couchdb
+ bin/couchdb
+
+7. Use your system's kernel trace tool and log the output of the above command.
+
+ a) For example, linux systems should use ``strace``:
+
+.. code-block:: text
+
+ strace bin/couchdb 2> strace.out
+
+8. Report back to the mailing list (or IRC) with the output of each step.
+
+
+Upgrading
+=========
+
+Are you upgrading from CouchDB 2.0? Install CouchDB into a fresh directory.
+CouchDB's directory layout has changed and may be confused by libraries
+present from previous releases.
+
+Runtime Errors
+==============
+
+Lots of memory being used on startup
+------------------------------------
+Is your CouchDB using a lot of memory (several hundred MB) on startup? This one
+seems to especially affect Dreamhost installs. It's really an issue with the
+Erlang VM pre-allocating data structures when ulimit is very large or
+unlimited. A detailed dicussion can be found on the erlang-questions list,
+but the short answer is that you should decrease ``ulimit -n`` or define
+``ERL_MAX_PORTS`` to something reasonable like 1024.
+
+erlang stack trace contains ``system_limit``, ``open_port``
+-----------------------------------------------------------
+Erlang has a default limit of 1024 ports, where each FD, tcp connection, and
+linked-in driver uses one port. You seem to have exceeded this. You can
+change it at runtime using the ``ERL_MAX_PORTS`` env variable.
+
+function raised exception (Cannot encode 'undefined' value as JSON)
+-------------------------------------------------------------------
+If you see this in the CouchDB error logs, the JavaScript code you are using
+for either a map or reduce function is referencing an object member that is
+not defined in at least one document in your database. Consider this
+document:
+
+.. code-block:: text
+
+ {
+ "_id":"XYZ123",
+ "_rev":"1BB2BB",
+ "field":"value"
+ }
+
+and this map function:
+
+.. code-block:: javascript
+
+ function(doc) {
+ emit(doc.name, doc.address);
+ }
+
+This will fail on the above document, as it does not contain a ``name`` or
+``address`` member. Instead, use guarding to make sure the function only
+accesses members when they exist in a document:
+
+.. code-block:: javascript
+
+ function(doc) {
+ if(doc.name && doc.address) {
+ emit(doc.name, doc.address);
+ }
+ }
+
+While the above guard will work in most cases, it's worth bearing JavaScript's
+understanding of 'false' values in mind. Testing against a property with a
+value of 0 (zero), ``''`` (empty String), ``false`` or ``null`` will return
+false. If this is undesired, a guard of the form ``if (doc.foo !== undefined)``
+should do the trick.
+
+This error can also be caused if a reduce function does not return a value. For
+example, this reduce function will cause an error:
+
+.. code-block:: javascript
+
+ function(key, values) {
+ sum(values);
+ }
+
+The function needs to return a value:
+
+.. code-block:: javascript
+
+ function(key, values) {
+ return sum(values);
+ }
+
+erlang stack trace contains ``bad_utf8_character_code``
+-------------------------------------------------------
+
+CouchDB 1.1.1 and later contains stricter handling of UTF8 encoding. If you are
+replicating from older versions to newer versions, then this error may occur
+during replication.
+
+A number of work-arounds exist; the simplest is to do an in-place upgrade of
+the relevant CouchDB and then compact prior to replicating.
+
+Alternatively, if the number of documents impacted is small, use filtered
+replication to exclude only those documents.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/1f6633f3/src/install/unix.rst
----------------------------------------------------------------------
diff --git a/src/install/unix.rst b/src/install/unix.rst
index 8332d63..26565c9 100644
--- a/src/install/unix.rst
+++ b/src/install/unix.rst
@@ -20,27 +20,7 @@ A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
This document is the canonical source of installation information. However, many
systems have gotchas that you need to be aware of. In addition, dependencies
-frequently change as distributions update their archives. If you're running into
-trouble, be sure to check out the wiki. If you have any tips to share, please
-also update the wiki so that others can benefit from your experience.
-
-.. seealso::
- `Community installation guides`_
-
-.. _Community installation guides: http://wiki.apache.org/couchdb/Installation
-
-Troubleshooting
-===============
-
-* There is a `troubleshooting guide`_.
-* There is a `wiki`_ for general documentation.
-* There are collection of `friendly mailing lists`_.
-
-Please work through these in order if you experience any problems.
-
-.. _troubleshooting guide: http://wiki.apache.org/couchdb/Troubleshooting
-.. _wiki: http://wiki.apache.org/couchdb
-.. _friendly mailing lists: http://couchdb.apache.org/community/lists.html
+frequently change as distributions update their archives.
.. _install/unix/dependencies:
@@ -174,6 +154,8 @@ From here you should verify your installation by pointing your web browser to::
http://localhost:5984/_utils/verify_install.html
+.. _install/unix/security:
+
Security Considerations
=======================
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/1f6633f3/src/install/windows.rst
----------------------------------------------------------------------
diff --git a/src/install/windows.rst b/src/install/windows.rst
index 89513bf..52d843b 100644
--- a/src/install/windows.rst
+++ b/src/install/windows.rst
@@ -69,21 +69,6 @@ Installation from sources
If you're Windows geek, this section is for you!
-Troubleshooting
----------------
-
-* There is a `troubleshooting guide`_.
-* There is a `wiki`_ for general documentation.
-* And some `Windows-specific tips`_.
-* There are collection of `friendly mailing lists`_.
-
-Please work through these in order if you experience any problems.
-
-.. _troubleshooting guide: http://wiki.apache.org/couchdb/Troubleshooting
-.. _wiki: http://wiki.apache.org/couchdb
-.. _friendly mailing lists: http://couchdb.apache.org/community/lists.html
-.. _Windows-specific tips: http://wiki.apache.org/couchdb/Quirks_on_Windows
-
Dependencies
------------